diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..35e2a1c --- /dev/null +++ b/README.en.md @@ -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. diff --git a/README.md b/README.md index 95e3030..61c3759 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/03-git-workflow.md b/docs/03-git-workflow.md index 6b3462e..b4fc15c 100644 --- a/docs/03-git-workflow.md +++ b/docs/03-git-workflow.md @@ -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