阿白叔andClaude Opus 4.7 dfa84743f9 docs: add product project spec, distinguish date vs semver tags
Distill task_assistant's COLLABORATION_AND_RELEASE_WORKFLOW into a
team-wide product project spec and clarify when each tag style applies.

- Add docs/08-product-spec.md: semver triplet (internal/display/tag),
  manifest schema, dist-channel separation, user-confirmed update
  flow, feedback/log handling, sensitive-info scan, release flow,
  minimum delivery checklist
- docs/03-git-workflow.md: split tagging into spec (YYYYMMDD) vs
  product (vX.Y.Z) sections, link to 08
- README.md, CLAUDE.md, AGENTS.md: update versioning section and doc
  index to reference 08

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 14:45:28 +08:00
2026-05-20 09:02:21 +08:00

team-guide

我们小团队的 AI 协作(vibe coding)开发约定。 1–3 人规模,规则不多但都是真踩过的坑。

这个仓库是什么

工作方式的唯一来源——不是项目代码,是怎么干活。覆盖:

  • 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
  • 怎么用 Codex(AGENTS.md、approval 模式、与 Claude Code 的分工)
  • 写代码时人和 AI 怎么分工(vibe coding 守则)
  • Git 工作流(分支、commit、PR、review、tag)
  • Skill 管理与项目规划节奏
  • 代码与产出风格(命名、注释、README、任务包、handoff)
  • 产品类项目(task_assistant 这类有版本、有发行包的)的设计与发版规范

每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。

语言策略

  • 给人看的:中文。README.md、docs/*.md、人填的 template (README、PR、handoff)都是中文。
  • 给 AI 看的:英文。CLAUDE.md、AGENTS.md、对应 template、 以及中文文档里的代码块 / 命令示例。
  • Commit / PR / 分支 / tag:英文。AI 工具和搜索都更吃英文 metadata。

目录

team-guide/
├── README.md                      ← 你正在看(中文,给人)
├── CLAUDE.md                      ← Claude Code 读的项目上下文(英文)
├── AGENTS.md                      ← Codex 读的项目上下文(英文)
├── docs/
│   ├── 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 清单
│   ├── 07-codex.md                ← Codex 使用、AGENTS.md 同步规则
│   └── 08-product-spec.md         ← 产品类项目的设计与发版规范
└── templates/
    ├── CLAUDE.md.template         ← 给 AI 看(英文)
    ├── AGENTS.md.template         ← 给 AI 看(英文)
    ├── README.md.template         ← 给人填(中文)
    ├── PR_DESCRIPTION.template.md ← 给人填(中文)
    └── HANDOFF_CHECKLIST.template.md ← 给人填(中文)

怎么用

  1. 新成员 —— 先读 docs/01-vibe-coding.md 和 docs/03-git-workflow.md,其他当参考手册查。
  2. 新项目 —— 从 templates/ 复制对应模板到新仓库填上。新仓库 根目录同时放 CLAUDE.md 和 AGENTS.md,两个文件保持同步 (见 docs/07-codex.md)。
  3. 不同意某条规则 —— 在本仓库开 PR 改它,不要私下绕开。

版本管理

按项目类型分两种 tag 风格:

  • 规范类(本仓库 team-guide、其他规约文档)—— 按日期: YYYYMMDD,比如 20260520。同一天多次发布加 -N 后缀 (20260520-2)。
  • 产品类(task_assistant、authoring-tool 这种有版本、有发行包 的)—— semver:v0.2.4。三处版本号必须同步(内部 0.2.4 / 显示 V0.2.4 / tag v0.2.4),细则见 docs/08-product-spec.md。

通用规则:

  • main(规范类)/ dev(产品类)永远是当前工作副本,随时合并。
  • Tag 一旦推到远端就不能改、不能删、不能 force-push。
  • 大改写新 tag,不动旧 tag。
  • 谁要"用某一版",告诉对方 tag 名(例:team-guide @ 20260520、 task_assistant @ v0.2.4)就行。

打 tag 的具体命令和场景见 docs/03-git-workflow.md 的 Tag 一节。

最近 tag 列表:git.simgreek.com/simgreek/team-guide/tags

License

Internal.

S
Description
Team working agreements for AI-assisted development
Readme
157 KiB
0 Stars 8 Watchers 0 Forks
Languages
Shell 61.6%
Batchfile 38.4%