docs: add Chinese README and dated-tag versioning rules
- Move English README to README.en.md, add Chinese README.md as the entry point - Cross-link both READMEs at the top - Add Tagging section to docs/03-git-workflow.md (YYYYMMDD format, immutable, annotated, daily-suffix collisions) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
1 parent
7f9ca07903
commit
411f0b8182
3 files changed
+149
-28
No files matched your search
@@ -0,0 +1,58 @@
|
||||
# team-guide
|
||||
|
||||
> 中文版:[README.md](README.md)
|
||||
|
||||
Working agreements for our team's AI-assisted ("vibe coding") development.
|
||||
Small team, English docs, opinionated but light.
|
||||
|
||||
## What this repo is
|
||||
|
||||
A single source of truth for **how we work**, not what we build. It covers:
|
||||
|
||||
- How we use Claude Code (CLAUDE.md, permissions, hooks, memory, skills)
|
||||
- How we collaborate with AI when writing code (vibe coding norms)
|
||||
- Git workflow (branches, commits, PRs, review)
|
||||
- Skill management and project planning rhythm
|
||||
- Code & deliverable style (naming, comments, READMEs, task packages, handoffs)
|
||||
|
||||
Every doc is short. If a rule needs more than half a page to justify, it
|
||||
probably isn't a rule yet — it's a discussion.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
team-guide/
|
||||
├── README.md ← you are here
|
||||
├── CLAUDE.md ← context Claude Code loads when working in this repo
|
||||
├── docs/
|
||||
│ ├── 01-vibe-coding.md ← how humans + AI split the work
|
||||
│ ├── 02-claude-code.md ← CLAUDE.md / permissions / hooks / memory / skills
|
||||
│ ├── 03-git-workflow.md ← branches, commits, PRs, review
|
||||
│ ├── 04-skills-and-planning.md ← skill catalog + planning cadence
|
||||
│ ├── 05-code-style.md ← naming, comments, structure
|
||||
│ └── 06-handoff.md ← task packages, handoff checklists
|
||||
└── templates/
|
||||
├── CLAUDE.md.template
|
||||
├── README.md.template
|
||||
├── PR_DESCRIPTION.template.md
|
||||
└── HANDOFF_CHECKLIST.template.md
|
||||
```
|
||||
|
||||
## How to use it
|
||||
|
||||
1. **New team member** — read `docs/01-vibe-coding.md` and `docs/03-git-workflow.md` first. The rest is reference.
|
||||
2. **Starting a new project** — copy the templates from `templates/` into the new repo and fill them in. Drop a top-level `CLAUDE.md` that points back here.
|
||||
3. **Disagreeing with a rule** — open a PR against this repo. Don't silently diverge.
|
||||
|
||||
## Versioning
|
||||
|
||||
Releases are tagged by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a
|
||||
snapshot of `main` from that day, suitable for "this is the version we
|
||||
agreed to follow." See `docs/03-git-workflow.md` for the tagging rules.
|
||||
|
||||
- Latest tag: see [`git tag --sort=-creatordate`](https://git.simgreek.com/simgreek/team-guide/tags) on the remote
|
||||
- `main` is always the working copy; tags are checkpoints
|
||||
|
||||
## License
|
||||
|
||||
Internal.
|
||||
@@ -1,34 +1,36 @@
|
||||
# team-guide
|
||||
|
||||
Working agreements for our team's AI-assisted ("vibe coding") development.
|
||||
Small team, English docs, opinionated but light.
|
||||
> English: [README.en.md](README.en.md)
|
||||
|
||||
## What this repo is
|
||||
我们小团队的 AI 协作(vibe coding)开发约定。
|
||||
1–3 人规模,英文写文档,规则不多但都是真踩过的坑。
|
||||
|
||||
A single source of truth for **how we work**, not what we build. It covers:
|
||||
## 这个仓库是什么
|
||||
|
||||
- How we use Claude Code (CLAUDE.md, permissions, hooks, memory, skills)
|
||||
- How we collaborate with AI when writing code (vibe coding norms)
|
||||
- Git workflow (branches, commits, PRs, review)
|
||||
- Skill management and project planning rhythm
|
||||
- Code & deliverable style (naming, comments, READMEs, task packages, handoffs)
|
||||
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
|
||||
|
||||
Every doc is short. If a rule needs more than half a page to justify, it
|
||||
probably isn't a rule yet — it's a discussion.
|
||||
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
|
||||
- 写代码时人和 AI 怎么分工(vibe coding 守则)
|
||||
- Git 工作流(分支、commit、PR、review)
|
||||
- Skill 管理与项目规划节奏
|
||||
- 代码与产出风格(命名、注释、README、任务包、handoff)
|
||||
|
||||
## Layout
|
||||
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
team-guide/
|
||||
├── README.md ← you are here
|
||||
├── CLAUDE.md ← context Claude Code loads when working in this repo
|
||||
├── README.md ← 中文版(你正在看)
|
||||
├── README.en.md ← English version
|
||||
├── CLAUDE.md ← Claude Code 在本仓库工作时加载的上下文
|
||||
├── docs/
|
||||
│ ├── 01-vibe-coding.md ← how humans + AI split the work
|
||||
│ ├── 02-claude-code.md ← CLAUDE.md / permissions / hooks / memory / skills
|
||||
│ ├── 03-git-workflow.md ← branches, commits, PRs, review
|
||||
│ ├── 04-skills-and-planning.md ← skill catalog + planning cadence
|
||||
│ ├── 05-code-style.md ← naming, comments, structure
|
||||
│ └── 06-handoff.md ← task packages, handoff checklists
|
||||
│ ├── 01-vibe-coding.md ← 人 + AI 怎么分工
|
||||
│ ├── 02-claude-code.md ← CLAUDE.md / permission / hook / memory / skill
|
||||
│ ├── 03-git-workflow.md ← 分支、commit、PR、review、tag
|
||||
│ ├── 04-skills-and-planning.md ← skill 目录 + 规划节奏
|
||||
│ ├── 05-code-style.md ← 命名、注释、结构
|
||||
│ └── 06-handoff.md ← 任务包、handoff 清单
|
||||
└── templates/
|
||||
├── CLAUDE.md.template
|
||||
├── README.md.template
|
||||
@@ -36,17 +38,31 @@ team-guide/
|
||||
└── HANDOFF_CHECKLIST.template.md
|
||||
```
|
||||
|
||||
## How to use it
|
||||
## 怎么用
|
||||
|
||||
1. **New team member** — read `docs/01-vibe-coding.md` and `docs/03-git-workflow.md` first. The rest is reference.
|
||||
2. **Starting a new project** — copy the templates from `templates/` into the new repo and fill them in. Drop a top-level `CLAUDE.md` that points back here.
|
||||
3. **Disagreeing with a rule** — open a PR against this repo. Don't silently diverge.
|
||||
1. **新成员** —— 先读 [`docs/01-vibe-coding.md`](docs/01-vibe-coding.md) 和 [`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。
|
||||
2. **新项目** —— 从 `templates/` 复制模板到新仓库填上,再在新仓库根目录放一个 `CLAUDE.md` 指回这里。
|
||||
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
|
||||
|
||||
## Versioning
|
||||
## 文档语言约定
|
||||
|
||||
This repo is versioned, not pinned. Read the latest `main`. Notable changes
|
||||
get a `CHANGELOG` entry once we have one; until then, `git log` is the
|
||||
changelog.
|
||||
- 仓库内所有 `.md` 用**英文**,包括 commit message、PR 标题、tag 注释。
|
||||
- 这个 README 提供中文入口;剩下的内容直接读英文版本。
|
||||
- 跟外部团队/客户的交付物按对方语言来——本仓库的规则只管内部。
|
||||
|
||||
## 版本管理
|
||||
|
||||
按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。
|
||||
|
||||
- `main` 永远是当前工作副本,随时合并。
|
||||
- 一天最多一个 tag。同一天有多次发布,用 `YYYYMMDD-N` 后缀(`20260520-2`)。
|
||||
- Tag 一旦推到远端就不能改、不能删、不能 force-push。
|
||||
- 大改写新 tag,不动旧 tag。
|
||||
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
|
||||
|
||||
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tagging 一节。
|
||||
|
||||
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -77,6 +77,51 @@ Author follow-ups:
|
||||
usually the right starting point.
|
||||
- Delete the branch on merge.
|
||||
|
||||
## Tagging (versioning)
|
||||
|
||||
We tag by date: `YYYYMMDD` (e.g. `20260520`). Each tag is a snapshot of
|
||||
`main` worth pointing at — "this is the version we agreed to follow."
|
||||
|
||||
Rules:
|
||||
|
||||
- Tag only on `main`. Tagging a feature branch is a smell.
|
||||
- One tag per day max. If you cut a second one the same day, suffix with
|
||||
`-N`: `20260520-2`, `20260520-3`.
|
||||
- Tag messages are annotated, not lightweight. Use `git tag -a` and
|
||||
write one or two sentences about what changed since the last tag.
|
||||
- A tag, once pushed, is immutable. No deleting, no moving, no force-tag.
|
||||
If the tag is wrong, cut a new one.
|
||||
- Tag the commit, push the tag, and announce the tag name. That's the
|
||||
release.
|
||||
|
||||
Cut a tag:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull --ff-only
|
||||
git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags"
|
||||
git push origin 20260520
|
||||
```
|
||||
|
||||
List / inspect:
|
||||
|
||||
```bash
|
||||
git tag --sort=-creatordate # newest first
|
||||
git show 20260520 # show what's in a tag
|
||||
git log --oneline 20260513..20260520 # what changed between tags
|
||||
```
|
||||
|
||||
When to cut a tag:
|
||||
|
||||
- The docs in this repo changed in a way teammates need to read.
|
||||
- A template was added, removed, or restructured.
|
||||
- A new convention is now in effect (not just proposed).
|
||||
|
||||
When NOT to cut a tag:
|
||||
|
||||
- Typo fixes, formatting, broken links → just push to `main`.
|
||||
- Drafts under discussion → use a PR, don't tag.
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- No `git push --force` to `main`. Period. To your own branch, only if
|
||||
@@ -84,6 +129,8 @@ Author follow-ups:
|
||||
- No `--no-verify` to skip hooks. Fix what the hook is complaining
|
||||
about.
|
||||
- No amending pushed commits. Once it's on the remote, add a new commit.
|
||||
- No deleting or moving tags after they've been pushed. Cut a new one
|
||||
instead.
|
||||
- No committing `.env`, credentials, or files larger than ~5 MB without
|
||||
a Git LFS conversation first.
|
||||
- No staging with `git add .` or `git add -A` when there are untracked
|
||||
|
||||
Reference in new issue
Block a user