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:
阿白叔andClaude Opus 4.7 committed 2026-05-20 09:22:38 +08:00
1 parent 7f9ca07903
commit 411f0b8182
3 files changed
+149 -28

No files matched your search

+58
View File
@@ -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.
+44 -28
View File
@@ -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
+47
View File
@@ -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