docs: collapse docs/ into single AGENTS.md, slim README

Single source of truth for AI is AGENTS.md. CLAUDE.md becomes a
one-line @AGENTS.md import so Claude Code and Codex read the same
spec — zero drift. README.md becomes a short Chinese entry point
(language policy, layout, tag styles, top pitfalls) and links into
AGENTS.md for full rules.

- Consolidate docs/01-08 into AGENTS.md (7 sections, ~700 lines)
- README.md: ~80-line Chinese entry point, no rule duplication
- CLAUDE.md: just "@AGENTS.md"
- Delete docs/ — content preserved in git history at tag 20260520-3

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
阿白叔andClaude Opus 4.7 committed 2026-05-20 16:56:19 +08:00
1 parent dfa84743f9
commit 94eb7ef70a
11 files changed
+976 -1298

No files matched your search

+932 -73
View File
File diff suppressed because it is too large. Load diff
+1 -109
View File
@@ -1,109 +1 @@
# CLAUDE.md — team-guide @AGENTS.md
Context for Claude Code working in this repository.
> Sister file: `AGENTS.md` (read by Codex). The two files cover the
> same ground — keep them in sync. Whichever tool runs reads its own
> file. See `docs/07-codex.md` for the sync rules.
## Project
This repo holds our team's working agreements (1–3 person team,
AI-assisted "vibe coding" development). It is **documentation, not code**.
There is no build, test, or lint step. Acceptance is "a human can read
the change and would have written the same."
## Editing rules
When editing files in this repo:
- One rule per bullet. If a rule needs a paragraph of justification,
split the rule out and put the justification on a `**Why:**` line.
- Lead with the rule, then `**Why:**`, then `**How to apply:**` only
when non-obvious. Skip them when the rule speaks for itself.
- No emoji. No decorative headers. No "🚀 Getting started!" energy.
- Keep each doc under ~150 lines. Past that, split.
- Examples beat prose. A 3-line code block beats a paragraph of
description.
## Language policy
- **Human-facing**: Chinese. `README.md`, `docs/*.md`, and the
human-fillable templates (`templates/README.md.template`,
`templates/PR_DESCRIPTION.template.md`,
`templates/HANDOFF_CHECKLIST.template.md`) are in Chinese.
- **AI-facing**: English. `CLAUDE.md`, `AGENTS.md`,
`templates/CLAUDE.md.template`, `templates/AGENTS.md.template`. Code
blocks and command examples inside Chinese docs also stay English.
- **Commit messages, PR titles, branch names, tag annotations**: English.
AI tools and search work better on English Git metadata.
If you're an agent and you're about to write Chinese into a file the
human would never read (or vice versa), stop — you have the wrong file.
## What goes where
| Topic | File |
| ---------------------------------------------- | --------------------------------- |
| Human + AI work split | `docs/01-vibe-coding.md` |
| Claude Code config (CLAUDE.md, hooks, memory) | `docs/02-claude-code.md` |
| Branches, commits, PRs, tagging | `docs/03-git-workflow.md` |
| Skill catalog, planning cadence | `docs/04-skills-and-planning.md` |
| Naming, comments, code style | `docs/05-code-style.md` |
| Task packages, handoff checklists | `docs/06-handoff.md` |
| Codex usage and AGENTS.md conventions | `docs/07-codex.md` |
| Product project spec (semver, manifest, build) | `docs/08-product-spec.md` |
## What NOT to do
- Don't add a doc for a rule we've used once. Wait until it's bitten
twice — then write it.
- Don't write process for processes' sake. If nobody would read or
follow it, don't write it.
- Don't quote external sources at length (license / copyright). Link
instead.
- Don't translate `CLAUDE.md` / `AGENTS.md` into Chinese. They're for
AI tools.
- Don't translate Chinese docs into English "for completeness." Pick
one language per file and stick with it.
## Commits
- Format: `<area>: <imperative summary under 60 chars>`. Examples:
`git-workflow: clarify branch naming`, `docs: add Codex section`.
- One topic per commit. "and" in the summary means split it.
- Always include the `Co-Authored-By` trailer when AI-assisted.
## Versioning / releases
Two tag styles, by project type:
- **Spec repos** (this one, other agreement docs) — date tags:
`YYYYMMDD`, with `-N` suffix for same-day reissues (`20260520-2`).
Tag from `main`.
- **Product repos** (task_assistant, authoring-tool — anything with
versioned artifacts shipped to users) — semver: `v<x.y.z>`. Tag from
`dev`. Internal version (`0.2.4`), display version (`V0.2.4`), and
tag (`v0.2.4`) must stay in sync. See `docs/08-product-spec.md` for
the full ruleset (manifest, release-field sync list, sensitive-info
scan, minimum delivery checklist).
Universal rules:
- Annotated tags only. Tag messages summarize what changed.
- Tags are immutable once pushed. If a tag is wrong, cut a new one.
- This repo is a spec repo, so tagging here means a date tag.
## Sync with AGENTS.md
If you change this file, update `AGENTS.md` to match (and vice versa).
The two files describe the same project to different tools — drift
breaks one of them silently. Reviewer should block PRs that touch only
one side.
## Working directory expectations
- The repo is small (≈20 files). You can `Read` everything before
acting; you don't need to spawn a sub-agent for exploration.
- Do not introduce `package.json`, `Makefile`, CI configs, or other
toolchain files unless explicitly asked. This is a docs repo.
+43 -59
View File
@@ -1,87 +1,71 @@
# team-guide # team-guide
我们小团队的 AI 协作(vibe coding)开发约定。 我们小团队的 AI 协作(vibe coding)开发约定。1–3 人规模,规则不多但都是真踩过的坑。
1–3 人规模,规则不多但都是真踩过的坑。
## 这个仓库是什么 完整规则在 [`AGENTS.md`](AGENTS.md)(英文,给 AI 看)——本仓库的**唯一规则来源**。
这份 README 是给人的导览,知道去哪查、怎么参与就行。
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖: ## 怎么用
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill) 1. **新成员** —— 读这份 README 五分钟,再扫一眼 [AGENTS.md](AGENTS.md) 的目录。具体规则用到再翻。
- 怎么用 Codex(AGENTS.md、approval 模式、与 Claude Code 的分工) 2. **新项目** —— 从 [`templates/`](templates/) 复制对应模板。新仓库根目录放 `AGENTS.md`,再放一行 `@AGENTS.md` 的 `CLAUDE.md`,让 Claude Code 和 Codex 读同一份。
- 写代码时人和 AI 怎么分工(vibe coding 守则) 3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
- Git 工作流(分支、commit、PR、review、tag)
- Skill 管理与项目规划节奏
- 代码与产出风格(命名、注释、README、任务包、handoff)
- 产品类项目(task_assistant 这类有版本、有发行包的)的设计与发版规范
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
## 语言策略 ## 语言策略
- **给人看的**:中文。`README.md`、`docs/*.md`、人填的 template - **给人看的(中文)**:本 README、`templates/` 里给人填的(README、PR、handoff)。
(README、PR、handoff)都是中文。 - **给 AI 看的(英文)**:[`AGENTS.md`](AGENTS.md)、[`CLAUDE.md`](CLAUDE.md)、AI 专用模板。
- **给 AI 看的**:英文。`CLAUDE.md`、`AGENTS.md`、对应 template、 - **Git 元数据(英文)**:commit、PR 标题、分支名、tag 注释。
以及中文文档里的代码块 / 命令示例。
- **Commit / PR / 分支 / tag**:英文。AI 工具和搜索都更吃英文 metadata。 理由:AI 工具和搜索更吃英文 metadata;规则只需要一份不需要两份;中文给人在入口处看到。
## 目录 ## 目录
``` ```
team-guide/ team-guide/
├── README.md ← 你正在看(中文,给人) ├── README.md ← 你正在看(中文,给人)
├── CLAUDE.md ← Claude Code 读的项目上下文(英文) ├── AGENTS.md ← 全部规则(英文,给 AI)
├── AGENTS.md ← Codex 读的项目上下文(英文) ├── CLAUDE.md ← 一行 @AGENTS.md import
├── docs/ └── templates/ ← 新项目脚手架
│ ├── 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 ← 给人填(中文)
``` ```
## 怎么用 [`AGENTS.md`](AGENTS.md) 内含 7 大章:
项目背景与编辑规则 · Vibe coding · Claude Code & Codex 配置 ·
1. **新成员** —— 先读 [`docs/01-vibe-coding.md`](docs/01-vibe-coding.md) 和 Git 工作流 · 代码与产出风格 · 产品类项目(semver、manifest、发版)·
[`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。 规划节奏 · Handoff。
2. **新项目** —— 从 `templates/` 复制对应模板到新仓库填上。新仓库
根目录同时放 `CLAUDE.md` 和 `AGENTS.md`,两个文件保持同步
(见 [`docs/07-codex.md`](docs/07-codex.md))。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
## 版本管理 ## 版本管理
按**项目类型**分两种 tag 风格: 按**项目类型**分两种 tag 风格:
- **规范类**(本仓库 team-guide、其他规约文档)—— 按日期: - **规范类**(本仓库 team-guide、其他规约文档)—— 按日期 `YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀(`20260520-2`)。从 `main` 打 tag。
`YYYYMMDD`,比如 `20260520`。同一天多次发布加 `-N` 后缀 - **产品类**(task_assistant、authoring-tool 这种有版本、有发行包的)—— semver `vX.Y.Z`,比如 `v0.2.4`。三处版本号必须同步:内部 `0.2.4` / 显示 `V0.2.4` / tag `v0.2.4`。从 `dev` 打 tag。
(`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`](docs/08-product-spec.md)。
通用规则: 通用规则:
- `main`(规范类)/ `dev`(产品类)永远是当前工作副本,随时合并。 - `main`(规范类)/ `dev`(产品类)永远是当前工作副本。
- Tag 一旦推到远端就不能改、不能删、不能 force-push。 - 只用 annotated tag(`git tag -a`)。
- 大改写新 tag,不动旧 tag。 - Tag 一旦推到远端就不能改、不能删、不能 force-push。错了切新的。
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`、 - 谁要"用某一版",告诉对方 tag 名(`team-guide @ 20260520`、`task_assistant @ v0.2.4`)就行。
`task_assistant @ v0.2.4`)就行。
打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 具体命令、什么时候切 tag、产品项目发版细则——见 [`AGENTS.md`](AGENTS.md) 的 Git workflow 和 Product projects 两节。
的 Tag 一节。
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags) ## 几条最容易踩的线(速查)
完整版在 AGENTS.md,这里挑人最常忘的:
- 长 session 的上下文会污染输出,新任务开新 session
- 不读 diff 就 "looks good" 是 bug 上线的标准姿势
- 一个 session 不要同时让 Claude Code 和 Codex 改同一个文件
- AI 试同一个方案两次报同样的错——叫停,自己上
- 改了 `CLAUDE.md` / `AGENTS.md` 一边,另一边要在同一个 PR 里同步(本仓库已经用 `@AGENTS.md` 解决了,新项目要注意)
- 提交前 `git diff --cached` 扫一眼,密钥误提交的应急流程在 AGENTS.md 的 Sensitive-info scan 节
- 产品发版"必改字段清单"漏一处下版就漂移——清单写进项目自己的 AGENTS.md
## 远端
[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) ·
[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags)
## License ## License
-77
View File
@@ -1,77 +0,0 @@
# 01 — Vibe coding(人机协作)
人和 AI 在团队里怎么分工。
## 前提
Claude / Codex 写大部分代码。人负责把方向:定义问题、做决策、判断
什么算"够好可以发"。我们不是在跟 AI 比谁打字快——是用 AI 把打字时间
省下来,多花点时间在思考上。
## 分工
**AI 干的:**
- 读代码、解释代码
- 拿到清晰 spec 后写第一版实现
- 机械重构(重命名、抽函数、改类型)
- 跑测试 / build / lint,按报错迭代
- 生成模板代码(配置、fixture、CRUD)
- 跨工作区搜索、汇总
**人干的:**
- 决定要做什么、为什么做
- 在 AI 动手前把 spec 写清楚
- 批准任何有外溢影响的改动(依赖、schema、infra、auth、密钥)
- 合并前读完每一行 diff
- AI 已经试错两次还在打转时,叫停
- 写 commit message 和 PR description(AI 起草,你定稿)
如果你觉得任务正在朝"AI 替我决策"漂移,先停下来自己写一段 spec。
## 提示词习惯
- **给框架,不给步骤。** 告诉 AI 目标、约束、你已经否决了哪些方案。
除非步骤本身就是关键,否则别一步步指挥。
- **点名文件。** "修一下 `eval-agent/runner.py` 里的 bug"比"修一下那个
bug"省一次搜索。
- **说清楚什么算完成。** "测试通过、新 flag 默认关"——可衡量。
"干净一点"——不行。
- **一轮一件事。** 三个不相关的请求就开三条对话或三个 session。
上下文混在一起,输出也会混。
- **看到不对就 push back。** diff 写错了就直说哪里错。别接受你自己
不会写出来的代码。
## 什么时候叫停 AI、自己上
出现以下情况停手:
- 同一个方案试了两次,错误信息都没变。
- AI 在加任务里没要求的"防御性代码"。
- diff 已经长到你一次坐下来读不完。
- 你没法在不重新看 diff 的情况下跟同事讲清楚改了什么。
- 它马上要做不可逆的事(删数据、force push、动 auth)——必须明确
确认。
如果你叫停了自己上,把"为什么叫停"写进 PR description——下一个人
不至于重蹈覆辙。
## 验收 AI 产出
把 AI 的每一份 diff 当一个跑得快的实习生 PR 来 review:
1. 能 build 吗?
2. 测试过吗——新写的测试是不是真的覆盖了新代码?
3. 改没改 spec 范围之外的文件?每个都看一遍。
4. 加依赖了吗?看 lockfile diff。
5. AI 加的注释一条条读。一半是噪音,删掉。
6. 用户可见的功能要端到端跑一遍。类型检查通过 ≠ 功能正常。
## 反模式
- **上下文滚雪球。** 长 session 会带进过期假设。新任务开新 session。
- **闭眼批准。** 不读 diff 就说"看着没问题"是 bug 上线的标准姿势。
读 diff。
- **把 spec 也外包了。** "你看着办"不是提示词,是逃避。
- **顺手改无关代码。** AI 想"既然来了顺便重构一下"——拒绝。开新任务。
-122
View File
@@ -1,122 +0,0 @@
# 02 — Claude Code
我们在每个项目里怎么配置和使用 Claude Code。
## 配置文件
每个项目应该有:
```
<repo>/
├── CLAUDE.md ← 项目上下文(提交进仓库)
├── AGENTS.md ← Codex / 通用 agent 上下文(提交)
└── .claude/
├── settings.json ← 共享设置(提交)
├── settings.local.json ← 个人覆盖(gitignore)
└── skills/ ← 项目级 skill(提交)
```
`settings.local.json` **永远** gitignore。个人 API key、本地路径、
个人 hook 调整都放这里。
`AGENTS.md` 见 [docs/07-codex.md](07-codex.md)——给 Claude 看 `CLAUDE.md`,
给 Codex 看 `AGENTS.md`,两个文件内容大体一致,工具读各自的。
## CLAUDE.md 的内容
每个 `CLAUDE.md` 按这个顺序回答:
1. **这是个什么项目?** 最多两句话。
2. **怎么跑?** Build、test、lint 命令,写成 bash 块。
3. **架构一段话。** 入口在哪、数据怎么流。除非能省字,否则不画图。
4. **本仓库特有的约定。** 命名、目录、那些不看注释看不出来的模式。
5. **不要做的事。** Claude 以前在这里翻过的车,每条一行。
新人(人或 AI)读一遍就该能上手干活。`CLAUDE.md` 超过 100 行,说明
它已经偷偷变成"文档"了,应该拆出去。
用 `templates/CLAUDE.md.template` 起手。
## 权限(permission)
默认姿态:**只读自由放行,能改的都问一下。**
`.claude/settings.json` 里可以无提示放行:
- 所有 `Read`、`Glob`、`Grep`
- `Bash(git status)`、`Bash(git diff)`、`Bash(git log)`、`Bash(git branch)`
- 项目特定的只读命令(`Bash(npm test)`、`Bash(pytest)` 这类)
永远要弹窗确认:
- 工作树之外的 `Edit` / `Write`
- 带破坏动词的 `Bash`(`rm`、`mv`、`git push`、`git reset --hard`、装包)
- 任何会跟外部服务对话的 MCP 工具
如果你发现自己在反复批准同一类提示,跑一下 `fewer-permission-prompts`
skill——它会扫 transcript 给你列一份允许列表。
## Hook(钩子)
Hook 是让 harness 自动执行规则的方式——AI 自己**不可靠地**记住"以后
都要 X",跨 session 会忘。
适合用 hook 的事:
- 文件保存后自动格式化(Prettier、ruff、gofmt)
- 阻止改受保护路径(`.env`、生成文件、`dist/`)
- 写测试路径后自动跑测试
- session 结束 / 长任务完成时通知
不适合用 hook 的:
- 一次性检查("这周记得 X 一下")
- 任何依赖 AI 判断的("觉得有必要就跑")
通过 `update-config` skill 配置,或者直接编辑 `.claude/settings.json`。
JSON 里每个 hook 加一行注释说明。
## Memory(记忆)
Harness 有按机器的记忆系统。用法:
- **User**:你是谁、角色、偏好。
- **Feedback**:你给 AI 的纠正,要跨 session 保留的(带上**为什么**)。
- **Project**:进行中工作的事实,代码里没写的(截止日期、相关方决策、
为什么要重构)。
- **Reference**:外部资源指针(Linear 项目、Grafana dashboard、内网 wiki)。
不要把 memory 内容塞进 `CLAUDE.md`。CLAUDE.md 是项目上下文,团队共享。
Memory 是个人的、按机器的,不进仓库。
不要把 memory 当便签本用。任务级别的东西塞进 plan 或 PR description。
## Skill(技能)
Skill 在三个地方:
- **用户级**(`~/.claude/skills/`)—— 装一次到处可用
- **项目级**(`<repo>/.claude/skills/`)—— 提交进仓库,团队共享
- **插件**—— 通过 marketplace 安装
同一个流程做了三次都一样,就提升成 skill。目录见
[docs/04-skills-and-planning.md](04-skills-and-planning.md)。
## Sub-agent(子 agent)
什么时候开 sub-agent(用 `Agent` 工具):
- 任务要跨很多文件搜索,又不想把搜索结果塞进主上下文。
- 想让另一个独立视角再看一遍设计或 diff。
- 工作真的并行(比如同时调研三个方案)。
主 agent 两次工具调用就能搞定的事,别开 sub-agent。交接成本不是免费
的。
## Session
- 一个 session 一个任务。新任务开新 session。
- session 跑长了、上下文条快满了:先收尾当前步骤,把状态总结进 plan
或 PR draft,然后开新 session。
- 别用 `--continue` 把昨天的 session 拉回来做新主题。陈旧上下文会
渗进来。
-153
View File
@@ -1,153 +0,0 @@
# 03 — Git 工作流
小团队,流程从轻。分支、commit、PR、review、tag。
## 分支
- `main` 永远可发。不直接 push,没有例外。
- 功能分支:`<owner>/<short-slug>` —— 比如 `bai/auth-retry`、
`bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。
- 长期集成分支:`integration/<topic>` —— 团队同意才用。
- 合并完删分支。老分支会污染搜索结果。
## Commit
格式:
```
<area>: <祈使句小结,60 字符以内>
<可选 body —— 写改了什么、为什么,不写怎么改>
```
- `<area>` 是目录或组件,小写:`eval-agent`、`task_assistant`、
`docs`、`git-workflow`。
- 祈使句:`add`、`fix`、`rename`,不要 `added` / `adding`。
- Body 在 ~72 字符换行。普通改动跳过 body。
- 一个 commit 一个主题。摘要里出现"and"——拆。
- AI 协作的 commit 保留 Claude Code 默认加的 `Co-Authored-By` trailer。
别去掉。
- Commit message 用英文(vibe coding 守则之一:给 AI 看的内容用英文)。
例:
```
eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming in git-workflow
task_assistant: drop unused legacy export path
```
## Pull Request
- 一个 PR 一个主题。一句话说不清楚——拆成多个 PR。
- 标题 70 字符以内,跟 commit 摘要同一形态。
- Description 用 `templates/PR_DESCRIPTION.template.md`。
- 第一次 push feature 分支用 `-u`,让它跟踪远端。
- 有可跑的东西就开 PR,draft 也行。边写边 review 比写完再 review 好。
## Review
每个 PR 都要 review,包括 AI 协作出的,自己也不能跳。
Reviewer 检查清单:
1. Description 跟 diff 对得上吗?diff 有惊喜——发问。
2. 改的每个文件都看一遍。文件跟主题无关——发问为什么进了 PR。
3. 改动不是显而易见就本地跑一遍。
4. 新依赖、schema 变更、env var、动 auth 的代码——讲清楚理由前
block。
5. 评论先发**最不重要**的;merge-blocker 留到最后,让它明显是闸门。
作者收尾:
- 每条评论都回应,哪怕只是"同意,已在 <commit> 修"。
- 不同意写出来 push back,不要默默忽略。
- 合并前把噪音 commit 压一下(squash fixup commits)。
## 合并
- Feature 分支用 squash。Merge commit 留给集成分支。
- 最终 squash message 按 commit 格式写。PR 标题通常就是好起点。
- 合并完删分支。
## Tag(版本管理)
按项目类型分两种 tag 风格:
| 项目类型 | Tag 格式 | 例子 | 用在哪儿 |
| -------- | ------------------- | -------------------------- | ------------------------------------- |
| 规范类 | `YYYYMMDD[-N]` | `20260520`、`20260520-2` | team-guide、规约文档、内部约定仓库 |
| 产品类 | `vX.Y.Z` | `v0.2.4` | task_assistant、有版本和发行包的产品 |
判断标准:会有"用户"拿到这个项目的版本化产物——产品类。否则——规范
类。详细规则见 [`docs/08-product-spec.md`](08-product-spec.md)。
每个 tag 是 `main` 某一时刻的快照——值得指着说"我们就按这版来"。
通用规则(两类都适用):
- 只在 `main`(规范类)或 `dev`(产品类)上打 tag。功能分支打 tag
是 smell。
- 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次
tag 以来改了什么。
- Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。
- Tag commit、push tag、告诉大家 tag 名字——这就是发布。
规范类专属:一天最多一个 tag。同一天再切一个,加 `-N` 后缀:
`20260520-2`、`20260520-3`。
产品类专属:semver 三元组、产品 README 必备版本字段同步、tag
message 用 `<Project> V<x.y.z>`——细则见
[`docs/08-product-spec.md`](08-product-spec.md)。
切 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
```
切 tag(产品类):
```bash
git checkout dev
git pull --ff-only <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
查看 / 对比:
```bash
git tag --sort=-creatordate # 按时间倒序
git show 20260520 # 看一个 tag 里有什么
git log --oneline 20260513..20260520 # 两个 tag 之间改了什么
```
什么时候切 tag(规范类):
- 本仓库的 docs 改了,队友需要重新读。
- 加了、删了或重组了 template。
- 新的约定正式生效(不是还在讨论)。
什么时候**不**切 tag(规范类):
- 改错别字、调格式、修死链 → 直接 push 到 `main`。
- 还在讨论的草稿 → 走 PR,不打 tag。
产品类切 tag 跟着发版走,触发条件由[最低交付标准](08-product-spec.md#最低交付标准每次可给别人用的版本)
决定。
## 不要做的事
- 不要 `git push --force` 到 `main`。永远不要。push 到自己分支
也只在确定没人 pull 过的情况下。
- 不要 `--no-verify` 跳 hook。修 hook 报的问题。
- 不要 amend 已经 push 的 commit。已经在远端的就加新 commit。
- 不要删或移已经 push 的 tag。错了就切新的。
- 不要提交 `.env`、密钥、或者 ~5 MB 以上的文件——大文件先聊
Git LFS。
- 有不认识的 untracked 文件时,不要 `git add .` / `git add -A`。
按文件名加。
-101
View File
@@ -1,101 +0,0 @@
# 04 — Skill 与规划
我们怎么管 skill 目录、小团队怎么排活。
## Skill 目录
"Skill"是 Claude Code 能调用的、命名好的可复用流程。我们维护三份:
- **个人**(`~/.claude/skills/`)—— 私人,每人自己管。
- **团队**(`<repo>/.claude/skills/`)—— 提交进仓库,跟项目共享。
- **打包 / 插件** —— 从 marketplace 装。
### 什么时候做 skill
工作流提升成 skill 要**同时**满足三条:
1. 你已经用同样的方式做过三次。
2. 步骤稳定到能写下来。
3. 别人按你写的也会做出同样的东西。
只满足两条——留在你的提示词笔记里。
### Skill 设计规则
- 一个 skill 一件事。要分支判断"用户想干什么"——拆成两个。
- 用动词短语命名:`review-pr`、`cut-release`、`rebuild-fixtures`。
不要 `pr-helper`。
- Description(模型看的那行字)说**什么时候触发**,不是 skill 干啥。
触发由模型判断。
- `SKILL.md` 200 行以内。长 skill 拆成阶段。
- 例子比说明强。给一个跑通的 run。
### Skill review
新 skill 当 PR 看:读、在真实任务上跑一次、merge。一个月没人用的
skill 归档(移到 `.claude/skills/_archive/`)。
### 当前活跃 skill(团队)
边走边维护。每条一行说明 + 路径。
```
# 推荐安装的(marketplace 或拷贝):
# anthropic-skills:consolidate-memory — 周期性 memory 整理
# simplify — review 改动找复用 / 质量问题
# fewer-permission-prompts — 从 transcript 提议 allowlist
# review — review pull request
# security-review — 对 pending 改动做安全 pass
# 团队 skill(本仓库):
# (还没有 —— 提升成 skill 后加进来)
```
## 规划节奏
我们 1–3 人。流程能保持对齐就够轻。当下做法:
### 每周
- 一次异步书面同步(周一上午)。每人发:
1. 上周交付了什么(每条一行)。
2. 这周准备捡什么(每条一行)。
3. 哪儿卡住或不清楚(**唯一**值得仔细读的部分)。
- 周中 30 分钟实时会。议题来自上面那条"卡住或不清楚"。
### 每个任务
要超过半天的活,开工前:
1. 写 5 行 spec:*目标 / 为什么 / 完成标准 / 范围外 / 风险*。
2. 在 PR description 里贴上(draft PR 也行),**写代码前**。
3. AI 要替你打字的话,这段 spec 就是提示词——直接喂进去。
收尾:
1. PR description 更新到跟实际交付一致。
2. 学到的、未来你想看到的,进 Claude memory(feedback / project 类型)
—— 见 [docs/02-claude-code.md](02-claude-code.md)。
### 每季度
留半天:
- 重读本仓库。过期的开 PR 改。
- 重审 skill 目录。不用的归档。
- 跑 `consolidate-memory` 整理个人 memory 文件。
## 项目结构
工作区下开新项目:
1. 复制 `templates/README.md.template` 和 `templates/CLAUDE.md.template`。
2. 立刻 `git init`,哪怕项目是一次性的。一次性项目活得比你想的久。
3. 第一个 commit 只放脚手架,没有真实代码。让 `git log` 后续好读。
4. 把项目加进工作区 README(有了之后),让别人能发现。
## 规划**不是**
- 不是 Jira ticket。两个人不需要看板。
- 不是 Gantt 图。需要 Gantt 说明在做错的东西。
- 不是状态秀。周一帖是为了发现卡点,不是证明你干了活。
-96
View File
@@ -1,96 +0,0 @@
# 05 — 代码与产出风格
命名、注释、结构。不论是人写的还是 AI 写的代码,都按这套来。
## 命名
- **文件** —— 小写。文档用连字符(`git-workflow.md`),Python 用
下划线(`task_runner.py`),JS/TS 跟生态走 kebab。匹配周围项目。
- **函数** —— 动词短语。`loadConfig` 不是 `config`;`runTask`
不是 `taskRunner`。
- **变量** —— 写它**是什么**,不写它的类型。`users` 不是
`userArray`;`retryCount` 不是 `n`。
- **布尔** —— `is*`、`has*`、`should*`。`isReady` 不是 `ready`。
- **常量** —— `UPPER_SNAKE_CASE` 仅用于真正的模块级常量。函数内用
普通 `const`。
- **不要缩写**——除非是领域术语。`database` 不是 `db`,`request`
不是 `req`。(Express handler 里的 `req`/`res` 是领域约定,可以。)
## 注释
默认不写。要写注释,**全部**条件成立:
- "为什么"从代码里看不出来。
- 未来读代码的人不写注释会读错。
- 代码本身改不清晰(重命名、抽函数、重组都试过)。
不要写:
- `// increment counter` 紧挨着 `counter++`
- `// added for the auth refactor` —— 这话该在 commit message 里
- 一大段 docstring 只是把签名复述一遍
- 没有 owner 没有日期的 TODO —— 它们会烂掉。要么现在修,要么开
issue,要么删了。
可以写:
- 一行解释一个非显而易见的 workaround,带上**为什么**。
- `# NOTE:` 标注会让读者意外的行为。
- 文件头注释,仅限于这个文件做的事目录结构没说清楚。
## 文件结构
- 一个文件一个概念。一句话说不清这个文件干啥——拆。
- 测试文件挨着代码放,除非项目本来就是平行测试树。
- 生成文件进 `dist/` / `build/` 这类目录,进 `.gitignore`。永远
不改生成文件。
- Lockfile 必须 commit,永远。
## 错误
- 在边界处(用户输入、外部 API、文件 I/O)大声失败。
- 不要 `try/except` 吞错。捕了就处理。
- 内部函数信任调用方,不要在三层深度上重复校验同一个输入。
- 日志里的错要带够上下文,光看日志能调试——做的什么操作、输入是
什么、走的哪条路径。
## 测试
- 测行为,不测实现。一个保留行为的重构把测试搞挂了——是测试错。
- 一个测试一个断言为佳。"啥都测的测试,挂了你不知道是哪一个挂了。"
- Fixture 和用它的测试放一起。
- 慢 / flaky 的测试加标记或隔离,不要默默重试。
- 没测试的新代码就是没写完——除非项目真的没有测试基础设施
(罕见,而且这本身是个 bug)。
## README
每个仓库都要有 `README.md`。按这个顺序回答:
1. **这是什么?** 一段话。
2. **怎么跑?** Setup / run / test 的 bash 块。
3. **怎么开发?** 代码在哪,约定是什么。
4. **数据从哪来 / 去哪?** 仅当不显然才写。
5. **指针。** 关联仓库、dashboard、文档。
用 `templates/README.md.template`。如果你的 README 比模板短,没问题
——把没用的 section 删掉。
## 交付物(任务包、数据集、导出)
给伙伴或下游交付时:
1. 文件名带版本:`<name>-v<n>.<ext>` 或 `<name>-<YYYYMMDD>.<ext>`。
一个项目一种约定,定了别变。
2. 配 `README` 写明 schema、生成日期、已知限制。
3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。
4. 生成它的 commit hash 写进 README。
完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。
## 不要做的事
- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
- 不要在功能 PR 里顺手重构无关代码。开新 PR。
- 不要没量就先优化。"可能慢"不是测量结果。
-103
View File
@@ -1,103 +0,0 @@
# 06 — Handoff(交接)
任务包、交付物、团队成员之间或对外部消费方的交接。
## 为什么这事重要
交接出问题的成本比原工作高。作者觉得"显然就是这么用的"的包,到接收方
手里是半天的迷茫。把交接当**交付物的一部分**对待,不是事后包装。
## 两种 handoff
1. **内部** —— 把工作交给队友(或未来的你)。通常是分支、PR、半成品
原型。
2. **外部** —— 给伙伴、客户或下游 pipeline 发版本化产物。通常是 zip、
数据集、release。
两种都用 `templates/HANDOFF_CHECKLIST.template.md`。外部的标准更高。
## 任务包
我们发的任务包(比如 `praxis-sample-5.zip`、
`task-assistant-v0.2-handoff-*.zip`)必须包含:
```
<package>/
├── README.md ← 这是什么、给谁用、怎么用
├── CHANGELOG.md ← 自上一版改了什么
├── VERIFICATION.md ← 计数、checksum、合理性检查
├── manifest.json ← 机器可读的元数据
├── data/ ← 真正的交付物
└── scripts/ ← 用这个包必须的脚本
```
`manifest.json` 至少要有:
```json
{
"name": "praxis-sample-5",
"version": "0.5.0",
"generated_at": "2026-05-18T17:00:00Z",
"source_commit": "<full sha>",
"source_repo": "<git remote url>",
"record_count": 1234,
"schema_version": "1.0"
}
```
填不出的字段写 `null`,在 README 里解释。**永远不要瞎编**。
## 内部 handoff(分支 / PR)
交出去之前:
- PR description 是最新的。Summary 写实际交付了什么,不是尝试过什么。
- PR template 里的 "test plan" 老老实实填。没测就说没测——别埋。
- AI 协作中让你意外的决策放进 `## Notes for reviewer`。"AI 先试了 X
不行因为 Y,最后用了 Z"——省 reviewer 重推一遍。
- 本地状态(env var、临时数据)要文档化或脚本化。"在我机器上能跑"
不算交接。
接收方应该能:
1. `git checkout` 这个分支
2. 读 PR description
3. 跑 test plan
4. 形成自己的判断
—— **不用问你**。如果接收方还要私聊你,handoff 就是不完整的。
## 外部 handoff(版本化产物)
标准更高。除上面任务包内容外:
- **可重现。** 有源码访问的人能从 `manifest.json` 里的 commit hash
重建产物。第一次发布前测一遍。
- **验证报告。** 一份机器可读(JSON 之类)的报告,记录预发检查的
通过情况。写清楚检查了什么、结果是什么。
- **来源(provenance)。** AI 协助生成的,写明用的哪个模型、人工
审核步骤是什么。不是为了仪式感——是为了半年后产物有问题时好查。
- **License 与署名。** 内部伙伴也要写。明确他们能用、不能用。
## 不要发的东西
- 没聊过传输渠道的 ~500 MB 以上文件。
- 含真实 PII 的内容——除非交付协议里就明确包含。
- `.env`、密钥、API key、内部主机名。
- "final final v3" 命名。用 version 字段。要是 final,那就是 `v1.0`。
- 没有 README 的包。一行 README 也比没有强。
## 收到 handoff 时
你是接收方:
1. 先**完整读** README。忍住直接跑脚本的冲动。
2. 跑一遍验证报告。不通过——停下来联系发送方再做任何事。
3. 任何意外(命名、缺文件、版本不对)一天内反馈给发送方。drift 不
反馈只会越来越歪。
## 模板
- `templates/HANDOFF_CHECKLIST.template.md` —— 每次交接填一份,跟
包一起发。
- `templates/PR_DESCRIPTION.template.md` —— 内部 handoff 走 PR 用。
-114
View File
@@ -1,114 +0,0 @@
# 07 — Codex
我们怎么在团队里用 Codex(CLI 与 IDE 集成),以及 `AGENTS.md` 怎么写。
## 为什么要规范
Codex 不读 `CLAUDE.md`。Claude Code 默认不读 `AGENTS.md`。两个工具在
同一个仓库里干活,看的是不同的"项目说明书"。如果只写一份,另一边就
是裸奔。
我们的做法:**两份都写,内容保持同步**。哪边的工具进来读哪边的文件。
## 文件分工
```
<repo>/
├── CLAUDE.md ← Claude Code 读的项目上下文
├── AGENTS.md ← Codex CLI / Codex IDE 读的项目上下文
└── docs/... ← 给人读的文档(中文)
```
两个文件**内容大体一致**:项目是什么、怎么跑、架构、本仓库特有的
约定、不要做什么。
它们的区别是:
- `CLAUDE.md` 偶尔会引用 Claude Code 特有的概念(skill、sub-agent、
permission mode、`.claude/settings.json`)。
- `AGENTS.md` 偶尔会引用 Codex 特有的概念(approval 模式、
`~/.codex/config.toml`、MCP server 配置)。
- 双方共有的部分(项目背景、命名约定、语言策略、commit 格式)必须
完全一致。
## 同步责任
谁改了 `CLAUDE.md`,谁顺手改 `AGENTS.md`(反之亦然)。在 PR 描述里
加一句"Synced AGENTS.md"或"Synced CLAUDE.md"——reviewer 一眼就能确认。
如果 PR 只改了一边,reviewer **block** 这个 PR,让作者补上。
要是哪天发现两边内容已经漂移得太远,开一个专门的 PR 重新对齐,
不要在功能 PR 里捎带修。
## Codex 使用约定
### 启动方式
- 终端:`codex`(不指定 prompt 进交互模式)或 `codex "<prompt>"`(一次性
任务)。在仓库根目录启动,让它能找到 `AGENTS.md`。
- IDE:用官方插件(VS Code / JetBrains)。仓库根目录的 `AGENTS.md`
自动加载。
### Approval 模式
默认用 `on-request`(命令前问一下)。机器是个人的、风险可控的环境
才用 `on-failure` 或 `never`。生产环境、共享机器、不熟悉的仓库——
保持 `on-request`。
调整方式见 Codex 文档;个人偏好放进 `~/.codex/config.toml`,**不要**
提交进仓库。
### 沙盒(sandbox)
- 写代码 + 跑测试:`workspace-write` + 网络 off。够用了。
- 需要联网装包 / fetch 资源:临时切 `workspace-write` + 网络 on,跑完
切回。
- `danger-full-access` 几乎不用。除非你知道自己在干嘛而且代价能承担。
### 不要让 Codex 干的事
跟 Claude Code 一样:
- 删数据、`git push --force`、改 auth、动密钥——**人决策**。
- 改 schema、加依赖、改 CI——**人审批**。
- 跨仓库的改动——**手动协调**,不要让 agent 一次推两个仓库。
## AGENTS.md 写法
每个项目的 `AGENTS.md` 按这个顺序写:
1. **项目** —— 一两句话定位。不要超过两句。
2. **怎么跑** —— Build / test / lint 命令,bash 块。
3. **架构** —— 一段话。入口、数据流、核心模块。能省字就省字。
4. **本仓库特有约定** —— 命名、目录、那些代码里看不出来的模式。
5. **语言策略** —— 哪些文件是中文(人看),哪些是英文(AI 看),
commit / PR / branch / tag 用什么语言。
6. **不要做的事** —— 翻过的车,每条一行。
100 行以内是目标,超出说明它在朝"通用文档"漂移,该拆。
模板见 `templates/AGENTS.md.template`。
## 工具选择建议
不是非此即彼,但有偏好:
- **写 docs / 写规范** —— Claude Code(这个仓库就是它写的)。
- **大段重构 / 跨多文件功能** —— Claude Code,因为有 plan mode 和
sub-agent。
- **窄范围编辑、跑个测试、改个配置** —— Codex CLI,启动快。
- **IDE 内 inline 改一段** —— Codex IDE 插件或 Cursor,看习惯。
两个工具混着用没问题,只要:
- 一个 session 一个工具(别又开 Claude Code 又开 Codex 改同一个文件,
互相覆盖很难追)。
- 两边产出的 commit 都按本仓库的 commit 格式([03-git-workflow.md](03-git-workflow.md))。
## 配置同步与个人覆盖
- 项目级:`AGENTS.md`、`CLAUDE.md`、`.claude/settings.json` 都进仓库。
- 个人级:`~/.codex/config.toml`、`~/.claude/settings.json`、
`.claude/settings.local.json`——**永远不进仓库**,gitignore 已经覆盖。
- 个人 token 永远不写进仓库里的任何文件,包括 `AGENTS.md`。
-291
View File
@@ -1,291 +0,0 @@
# 08 — 产品类项目规范
把 task_assistant 这类**有版本、有发行包、有用户使用**的项目从设计
到发布要遵循的约定写下来。规范性文件(像本仓库 team-guide 自己)按
日期 tag;产品代码按 semver。
## 两类项目的分界
| 维度 | 规范类(team-guide、规约文档) | 产品类(task_assistant、authoring-tool) |
| ---------- | ----------------------------- | ---------------------------------------- |
| 内容 | 文档、约定、模板 | 可执行代码、可发行的产物 |
| Tag 格式 | `YYYYMMDD` / `YYYYMMDD-N` | `v<major>.<minor>.<patch>` |
| 验收 | 人能读懂 | 测试通过、能跑起来 |
| 分发渠道 | Git 仓库本身 | Git(源码)+ 分发渠道(OpenList、HF 等) |
| 版本字段同步 | 没有 | 多处必须同步(见下文) |
| 用户 | 团队成员 | 真实使用者 |
不确定一个项目是哪类,问自己:"会有'用户'拿到这个项目的版本化产物
吗?" 会就是产品类。
## 版本号
**Semver 三元组**:`major.minor.patch`。
- **major** —— 不向后兼容的改动(schema 改了、CLI 参数改了、产物格式改了)
- **minor** —— 向后兼容的功能增加
- **patch** —— bug fix、性能优化、内部重构
我们的项目内部用三种写法,**三处必须同步**:
| 用途 | 格式 | 例子 | 在哪儿出现 |
| ------------ | ------------------ | ---------------- | ----------------------------------- |
| 内部版本号 | `X.Y.Z` | `0.2.4` | `package.json`、`pyproject.toml` |
| 显示版本号 | `VX.Y.Z` | `V0.2.4` | UI 胶囊、README 标题、release note |
| Git tag | `vX.Y.Z` | `v0.2.4` | Git tag 名 |
发布时**一个不能漏**的同步检查清单(用 task_assistant 举例):
```
package.json "version": "0.2.4"
public/index.html version chip 初始值
server.js fallback 版本
scripts/build-release.js fallback 版本 + release notes
scripts/build-release-windows.js fallback 版本 + release notes
README.md 标题、版本状态段
README.en.md 同上
```
每个项目都该在 README 里列一份"发版必改的版本字段"清单,**位置写
死**。漏一处下一版就漂移。
## Tag
```bash
git tag -a v0.2.4 HEAD -m "<project-name> V0.2.4"
git push <remote> v0.2.4
```
规则:
- 用 annotated tag(`-a`),不用 lightweight。
- Tag message 用英文,格式 `<Project Name> V<x.y.z>`,跟 displayVersion
一致。
- 一个版本一个 tag。同版本不同平台不要分多个 tag。
- 已经用于发行的 tag **不要移动**。错了发 patch(`v0.2.5`)覆盖。
- 误打的 tag 在**没用于发行前**可以删:
```bash
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
```
## 分支策略
产品类项目至少有:
- **`dev`** —— 默认协作分支。日常开发、bug 修复、文档更新、发行前
准备都进这里。
- **功能分支** —— `<owner>/<slug>`,开 PR 合到 `dev`。
不留含义不清的 `master`。需要稳定分支时用明确名字,比如:
```
release/v0.3
release/v0.3-hotfix
```
发布从 `dev` 起步——拉取 → 检查 → 改版本号 → 打 tag → 构建 → 上传。
## Git 与分发分家
**Git 管源码,分发渠道(OpenList / Hugging Face / 其他)管发行物**。
两者职责不混。
进 Git:
- 源代码、构建脚本、文档、协作规范、必要的小型静态资源、模板、
role / 配置表。
不进 Git:
```
config/ 本地配置
logs/ 运行日志
feedback-records/ 用户反馈
generated_task_packages/ 任务输出
reports/ 验证报告
runtime-temp/ 临时运行态
release/ release-build/ release-dev/ release-merge/
.venv/ __pycache__/ node_modules/
```
进分发渠道(典型路径,按项目调):
```
/<project>/dist/ 面向使用者的发行 zip + manifest
/<project>/feedback/<machine-id>/ 用户上传的反馈
```
发行 zip **必须自包含**:用户解压点击就能跑,不在用户机器上装
依赖。具体内容随项目变,但原则不变。
## Manifest
每次发布在分发渠道根目录放一份 `manifest.json`,客户端启动时读它判
断有没有更新:
```json
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
```
上传后**重新拉一遍** manifest,肉眼对一遍 size 和 sha256 是不是新的。
看到 size 跟旧版一致——分发渠道有缓存或上传出错。
## 更新机制
我们做的是"用户确认式更新",不是无人值守强推:
1. 客户端启动时拉 manifest,比版本号。
2. 有新版**提示用户**,不直接下载。
3. 用户点同意,下载到本地。
4. 用户点安装,重启生效。
任何一步不要替用户跳过。这条往后写进每个产品的 `CLAUDE.md` /
`AGENTS.md` 的"Don'ts"。
## 反馈与日志
反馈走"本地优先 + 异步上传":
```
本地:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
云端(上传成功后):
/<project>/feedback/<machine-id>/<feedback-file>.json
```
规则:
- 上传**失败不影响本地保存**。UI 提示"本地已存,上传失败可重试"。
- 反馈和日志**必须脱敏**:API key、Bearer token、cookie、password、
secret、私密账号——发上去之前在客户端就抹掉。
- 排查问题时让用户走反馈页提交,**不要**让用户直接发 `config/` 或
完整日志目录。
## 敏感信息检查
提交前每次都做:
```bash
git diff --cached
```
定期跑关键词扫描(PowerShell 例子见 task_assistant 的
COLLABORATION_AND_RELEASE_WORKFLOW.md,bash 大致等价):
```bash
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
```
命中**必须人工判断**,不能照单提交,也不能照单删(注释里的 demo
key 跟真 key 都会命中)。
误提交真密钥的应急流程:
1. **立刻**让对应 key/token 失效。
2. 删除或更换本地配置。
3. 通知协作者。
4. 评估要不要重写 Git 历史(`git filter-repo` 或团队约定的方式)。
只追加一个"删除 key"的 commit 是**不够安全**的——历史里仍然能看到。
## 发版流程(标准动作)
```bash
# 1. 同步
git checkout dev
git pull --ff-only <remote> dev
git status --short --branch
# 2. 检查
<lint command>
<test command>
# 3. 改版本号(按本项目的"必改清单"逐项改)
# package.json、UI 胶囊、server.js、build script、README
# 4. commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. 构建
<build command>
# 6. 上传 manifest + zip 到分发渠道,验证 size/sha256
```
## 产品 README 必备段落
每个产品类项目的 README,在通用 README 模板基础上,**额外**包含:
- **版本状态段** —— 当前源码版本、内部版本号、协作分支、协作仓库、
历史迁移来源(如果有)、默认本地服务地址(如果有)、默认输出
目录。
- **快速启动段** —— 按平台分(Windows / macOS / Linux),覆盖
解压、启动、访问、关闭。
- **发行包内置内容清单** —— 让用户知道完整包应该有什么。
- **发版必改字段清单** —— 给开发者的,写明哪些文件要同步改版本号。
人填模板见 [`templates/README.md.template`](../templates/README.md.template);
产品项目按上面清单加段落。
## 最低交付标准(每次"可给别人用"的版本)
照搬 task_assistant 的清单,按项目改:
- [ ] `<remote>/dev` 有对应 commit
- [ ] `<remote>` 有对应 tag(`v<x.y.z>`)
- [ ] `package.json` / `pyproject.toml` 版本正确
- [ ] UI 上版本胶囊显示正确
- [ ] Lint / typecheck / test 全通过
- [ ] 分发渠道 manifest 指向正确平台包
- [ ] manifest 的 size / sha256 与实际文件一致
- [ ] 发行包解压点击启动脚本即可运行
- [ ] 包内**没有** API key、日志、用户反馈、生成产物、验证报告
任意一项没勾——不算"可给别人用"。
## 项目里要落地什么
新建产品类项目时,除了 [`docs/02-claude-code.md`](02-claude-code.md)
里的标准(`CLAUDE.md` + `AGENTS.md` + `.claude/`),还要:
1. **`docs/COLLABORATION_AND_RELEASE_WORKFLOW.md`**(或类似名字)——
这份团队规范的项目特化版,包含本项目的版本字段清单、构建命令、
分发路径。task_assistant 那份就是范本。
2. **`scripts/build-release.*`** —— 构建脚本,输出 zip + 更新
`manifest.json`。
3. **发版必改字段清单** —— 写进 `CLAUDE.md` / `AGENTS.md` 或上面那份
workflow 里,**唯一来源**。
4. **CHANGELOG.md** —— 一个版本一段,按 semver 顺序排,简述用户能感
知的改动。
不必落地的(YAGNI):
- 复杂的发版编排工具(Lerna、Changesets)—— 人手够了。
- 自动化 release notes 生成 —— commit message 够好就够用。
- 多环境配置体系 —— 真有需要再说。