diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6fffdea
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,91 @@
+# AGENTS.md — team-guide
+
+Context for AI coding agents (Codex CLI, Codex in IDEs, other
+AGENTS.md-aware tools) working in this repository.
+
+> Sister file: `CLAUDE.md` (read by Claude Code). The two files cover
+> the same ground — keep them in sync. Whichever tool runs reads its
+> own file.
+
+## 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`, and
+ `docs/07-codex.md`'s code blocks / examples are in 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, 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` |
+
+## 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: `: `. 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
+
+- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same
+ day get a `-N` suffix (`20260520-2`).
+- Annotated tags only. Tag messages summarize what changed since the
+ previous tag.
+- Tags are immutable once pushed. If a tag is wrong, cut a new one.
+- Tag only on `main`.
+
+## Working directory expectations
+
+- The repo is small (10–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.
diff --git a/CLAUDE.md b/CLAUDE.md
index 01fd08b..9e71457 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,46 +1,97 @@
# CLAUDE.md — team-guide
-This repo holds our team's working agreements. When editing it, behave like
-a careful technical writer, not a coder.
+Context for Claude Code working in this repository.
-## Context
+> 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.
-- **Audience**: 1–3 person team, AI-assisted development ("vibe coding").
-- **Language**: English. All docs, all commits, all PR titles.
-- **Tone**: short, declarative, opinionated. No fluff, no hedging, no marketing voice.
+## 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
-- One rule per bullet. If a rule needs a paragraph of justification, split
- the rule out and put the justification in a *Why* line.
-- Lead with the rule, then `**Why:**`, then `**How to apply:**` only when
- the rule is non-obvious. Skip them when the rule speaks for itself.
+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. If it's growing past that, the doc is
- probably two docs.
-- Examples beat prose. Prefer a 3-line code block over a paragraph
- describing the code.
+- 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
-| If you're writing about… | Put it in… |
-| ---------------------------------------- | -------------------------------- |
-| How humans and AI split a task | `docs/01-vibe-coding.md` |
-| Claude Code config (CLAUDE.md, hooks…) | `docs/02-claude-code.md` |
-| Branches, commits, PRs | `docs/03-git-workflow.md` |
-| Which skills to install, planning cadence| `docs/04-skills-and-planning.md` |
-| Naming, comments, file structure | `docs/05-code-style.md` |
-| Task packages, handoff between members | `docs/06-handoff.md` |
+| 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` |
## What NOT to do
-- Don't add a doc for a rule we've used once. Wait until it's bitten us
+- 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 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
-- Commit message: `: ` — e.g. `git-workflow: clarify branch naming`.
-- One topic per commit. If a commit message has "and" in it, it's two commits.
+- Format: `: `. 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
+
+- Tags follow `YYYYMMDD` (e.g. `20260520`). Multiple tags on the same
+ day get a `-N` suffix (`20260520-2`).
+- Annotated tags only. Tag messages summarize what changed since the
+ previous tag.
+- Tags are immutable once pushed. If a tag is wrong, cut a new one.
+- Tag only on `main`.
+
+## 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.
diff --git a/README.en.md b/README.en.md
deleted file mode 100644
index 35e2a1c..0000000
--- a/README.en.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# 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 61c3759..d4abd72 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,61 @@
# team-guide
-> English: [README.en.md](README.en.md)
-
我们小团队的 AI 协作(vibe coding)开发约定。
-1–3 人规模,英文写文档,规则不多但都是真踩过的坑。
+1–3 人规模,规则不多但都是真踩过的坑。
## 这个仓库是什么
工作方式的唯一来源——不是项目代码,是**怎么干活**。覆盖:
- 怎么用 Claude Code(CLAUDE.md、permission、hook、memory、skill)
+- 怎么用 Codex(AGENTS.md、approval 模式、与 Claude Code 的分工)
- 写代码时人和 AI 怎么分工(vibe coding 守则)
-- Git 工作流(分支、commit、PR、review)
+- Git 工作流(分支、commit、PR、review、tag)
- Skill 管理与项目规划节奏
- 代码与产出风格(命名、注释、README、任务包、handoff)
每篇都很短。一条规则要超过半页才能解释清楚的,多半还不是规则——是个待讨论项。
+## 语言策略
+
+- **给人看的**:中文。`README.md`、`docs/*.md`、人填的 template
+ (README、PR、handoff)都是中文。
+- **给 AI 看的**:英文。`CLAUDE.md`、`AGENTS.md`、对应 template、
+ 以及中文文档里的代码块 / 命令示例。
+- **Commit / PR / 分支 / tag**:英文。AI 工具和搜索都更吃英文 metadata。
+
## 目录
```
team-guide/
-├── README.md ← 中文版(你正在看)
-├── README.en.md ← English version
-├── CLAUDE.md ← Claude Code 在本仓库工作时加载的上下文
+├── 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 清单
+│ ├── 06-handoff.md ← 任务包、handoff 清单
+│ └── 07-codex.md ← Codex 使用、AGENTS.md 同步规则
└── templates/
- ├── CLAUDE.md.template
- ├── README.md.template
- ├── PR_DESCRIPTION.template.md
- └── HANDOFF_CHECKLIST.template.md
+ ├── 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/01-vibe-coding.md) 和 [`docs/03-git-workflow.md`](docs/03-git-workflow.md),其他当参考手册查。
-2. **新项目** —— 从 `templates/` 复制模板到新仓库填上,再在新仓库根目录放一个 `CLAUDE.md` 指回这里。
+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` 和 `AGENTS.md`,两个文件保持同步
+ (见 [`docs/07-codex.md`](docs/07-codex.md))。
3. **不同意某条规则** —— 在本仓库开 PR 改它,不要私下绕开。
-## 文档语言约定
-
-- 仓库内所有 `.md` 用**英文**,包括 commit message、PR 标题、tag 注释。
-- 这个 README 提供中文入口;剩下的内容直接读英文版本。
-- 跟外部团队/客户的交付物按对方语言来——本仓库的规则只管内部。
-
## 版本管理
按日期打 tag,格式 `YYYYMMDD`,比如 `20260520`。
@@ -60,7 +66,7 @@ team-guide/
- 大改写新 tag,不动旧 tag。
- 谁要"用某一版",告诉对方 tag 名(例:`team-guide @ 20260520`)就行。
-打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tagging 一节。
+打 tag 的具体命令和场景见 [`docs/03-git-workflow.md`](docs/03-git-workflow.md) 的 Tag 一节。
最近 tag 列表:[git.simgreek.com/simgreek/team-guide/tags](https://git.simgreek.com/simgreek/team-guide/tags)
diff --git a/docs/01-vibe-coding.md b/docs/01-vibe-coding.md
index 5bf86ba..9b3f000 100644
--- a/docs/01-vibe-coding.md
+++ b/docs/01-vibe-coding.md
@@ -1,84 +1,77 @@
-# 01 — Vibe coding
+# 01 — Vibe coding(人机协作)
-How humans and AI split the work on this team.
+人和 AI 在团队里怎么分工。
-## The premise
+## 前提
-Claude Code writes most of the code. Humans steer: framing problems,
-making decisions, deciding what's good enough to ship. We're not racing
-the AI — we're using it to skip typing so we can spend more time
-thinking.
+Claude / Codex 写大部分代码。人负责把方向:定义问题、做决策、判断
+什么算"够好可以发"。我们不是在跟 AI 比谁打字快——是用 AI 把打字时间
+省下来,多花点时间在思考上。
-## The split
+## 分工
-**Claude does:**
+**AI 干的:**
-- Read code and explain it
-- Write first-pass implementations against a clear spec
-- Refactor mechanically (renames, extractions, type changes)
-- Run tests, builds, linters; iterate on errors
-- Generate boilerplate (configs, fixtures, templates, CRUD)
-- Search across the workspace and summarize findings
+- 读代码、解释代码
+- 拿到清晰 spec 后写第一版实现
+- 机械重构(重命名、抽函数、改类型)
+- 跑测试 / build / lint,按报错迭代
+- 生成模板代码(配置、fixture、CRUD)
+- 跨工作区搜索、汇总
-**Humans do:**
+**人干的:**
-- Decide what to build and why
-- Frame the spec before Claude touches code
-- Approve any change with non-local consequences (deps, schema, infra, auth, secrets)
-- Read every diff before merging
-- Make the call when Claude has tried twice and is going in circles
-- Write the commit message and PR description (Claude drafts; you sign off)
+- 决定要做什么、为什么做
+- 在 AI 动手前把 spec 写清楚
+- 批准任何有外溢影响的改动(依赖、schema、infra、auth、密钥)
+- 合并前读完每一行 diff
+- AI 已经试错两次还在打转时,叫停
+- 写 commit message 和 PR description(AI 起草,你定稿)
-If a task feels like it's drifting toward "Claude decides", stop and
-write a short spec yourself first.
+如果你觉得任务正在朝"AI 替我决策"漂移,先停下来自己写一段 spec。
-## Prompt habits
+## 提示词习惯
-- **Frame, don't dictate.** Tell Claude the goal, the constraints, and
- what you've already ruled out. Don't prescribe steps unless the steps
- are the point.
-- **Name the file.** "Fix the bug in `eval-agent/runner.py`" is better
- than "fix the bug." Save Claude a search.
-- **Say what done looks like.** "Tests pass and the new flag defaults to
- off" — measurable. "Make it cleaner" — not.
-- **One task per turn.** If you have three unrelated asks, send three
- messages or open three sessions. Mixed contexts produce mixed results.
-- **Push back on bad output.** If the diff is wrong, say so plainly and
- point at the part that's wrong. Don't accept code you wouldn't write
- yourself.
+- **给框架,不给步骤。** 告诉 AI 目标、约束、你已经否决了哪些方案。
+ 除非步骤本身就是关键,否则别一步步指挥。
+- **点名文件。** "修一下 `eval-agent/runner.py` 里的 bug"比"修一下那个
+ bug"省一次搜索。
+- **说清楚什么算完成。** "测试通过、新 flag 默认关"——可衡量。
+ "干净一点"——不行。
+- **一轮一件事。** 三个不相关的请求就开三条对话或三个 session。
+ 上下文混在一起,输出也会混。
+- **看到不对就 push back。** diff 写错了就直说哪里错。别接受你自己
+ 不会写出来的代码。
-## When to stop and take over
+## 什么时候叫停 AI、自己上
-Stop letting Claude drive when:
+出现以下情况停手:
-- It's failed the same approach twice and the error is unchanged.
-- It's adding code "for safety" that the task didn't ask for.
-- The diff has grown past what you can read in one sitting.
-- You can't explain the change to a teammate without re-reading the diff.
-- It's about to do something irreversible (delete data, force-push,
- change auth) — confirm explicitly.
+- 同一个方案试了两次,错误信息都没变。
+- AI 在加任务里没要求的"防御性代码"。
+- diff 已经长到你一次坐下来读不完。
+- 你没法在不重新看 diff 的情况下跟同事讲清楚改了什么。
+- 它马上要做不可逆的事(删数据、force push、动 auth)——必须明确
+ 确认。
-If you stop and take over, write down *why* in the PR description so
-the next person doesn't repeat the loop.
+如果你叫停了自己上,把"为什么叫停"写进 PR description——下一个人
+不至于重蹈覆辙。
-## Verifying AI output
+## 验收 AI 产出
-Treat every Claude diff like a PR from a fast junior:
+把 AI 的每一份 diff 当一个跑得快的实习生 PR 来 review:
-1. Does it build?
-2. Do the tests pass — and do new tests actually test the new code?
-3. Did it touch files outside the stated scope? Look at every one.
-4. Did it add deps? Check the lockfile diff.
-5. Read every comment Claude added. Half of them are noise — delete those.
-6. Run the feature end-to-end if it's user-facing. Type checks ≠ working software.
+1. 能 build 吗?
+2. 测试过吗——新写的测试是不是真的覆盖了新代码?
+3. 改没改 spec 范围之外的文件?每个都看一遍。
+4. 加依赖了吗?看 lockfile diff。
+5. AI 加的注释一条条读。一半是噪音,删掉。
+6. 用户可见的功能要端到端跑一遍。类型检查通过 ≠ 功能正常。
-## Anti-patterns
+## 反模式
-- **Snowballing context.** Long sessions accumulate stale assumptions.
- Start a new session for a new task.
-- **Approval-by-default.** "Looks good" without reading the diff is how
- bugs ship. Read it.
-- **Outsourcing the spec.** "Figure out what we should do" is not a
- prompt — it's avoidance.
-- **Letting AI rewrite history.** If Claude wants to refactor unrelated
- code "while we're here", say no. Open a separate task.
+- **上下文滚雪球。** 长 session 会带进过期假设。新任务开新 session。
+- **闭眼批准。** 不读 diff 就说"看着没问题"是 bug 上线的标准姿势。
+ 读 diff。
+- **把 spec 也外包了。** "你看着办"不是提示词,是逃避。
+- **顺手改无关代码。** AI 想"既然来了顺便重构一下"——拒绝。开新任务。
diff --git a/docs/02-claude-code.md b/docs/02-claude-code.md
index 018ce1b..1e50c89 100644
--- a/docs/02-claude-code.md
+++ b/docs/02-claude-code.md
@@ -1,129 +1,122 @@
# 02 — Claude Code
-How we configure and use Claude Code across projects.
+我们在每个项目里怎么配置和使用 Claude Code。
-## Configuration files
+## 配置文件
-Each project should have:
+每个项目应该有:
```
/
-├── CLAUDE.md ← project context (committed)
+├── CLAUDE.md ← 项目上下文(提交进仓库)
+├── AGENTS.md ← Codex / 通用 agent 上下文(提交)
└── .claude/
- ├── settings.json ← shared settings (committed)
- ├── settings.local.json ← personal overrides (gitignored)
- └── skills/ ← project-local skills (committed)
+ ├── settings.json ← 共享设置(提交)
+ ├── settings.local.json ← 个人覆盖(gitignore)
+ └── skills/ ← 项目级 skill(提交)
```
-`settings.local.json` is **always** gitignored. Personal API keys, local
-paths, and individual hook tweaks live there.
+`settings.local.json` **永远** gitignore。个人 API key、本地路径、
+个人 hook 调整都放这里。
-## CLAUDE.md content
+`AGENTS.md` 见 [docs/07-codex.md](07-codex.md)——给 Claude 看 `CLAUDE.md`,
+给 Codex 看 `AGENTS.md`,两个文件内容大体一致,工具读各自的。
-Every `CLAUDE.md` answers, in this order:
+## CLAUDE.md 的内容
-1. **What is this project?** Two sentences max.
-2. **How do I run it?** Build, test, lint commands as bash blocks.
-3. **Architecture in one paragraph.** Where the entry points are and
- how data flows. No diagrams unless they save words.
-4. **Conventions specific to this repo.** Naming, layout, patterns
- that aren't obvious from the code.
-5. **Don'ts.** Things Claude has gotten wrong before. One line each.
+每个 `CLAUDE.md` 按这个顺序回答:
-A new contributor (human or AI) should be productive after reading it
-once. If a `CLAUDE.md` is over 100 lines, it's drifted into documentation
-and should be split.
+1. **这是个什么项目?** 最多两句话。
+2. **怎么跑?** Build、test、lint 命令,写成 bash 块。
+3. **架构一段话。** 入口在哪、数据怎么流。除非能省字,否则不画图。
+4. **本仓库特有的约定。** 命名、目录、那些不看注释看不出来的模式。
+5. **不要做的事。** Claude 以前在这里翻过的车,每条一行。
-Use `templates/CLAUDE.md.template` as the starting point.
+新人(人或 AI)读一遍就该能上手干活。`CLAUDE.md` 超过 100 行,说明
+它已经偷偷变成"文档"了,应该拆出去。
-## Permissions
+用 `templates/CLAUDE.md.template` 起手。
-Default permission posture: **prompt for everything risky, allow read-only
-freely.**
+## 权限(permission)
-In `.claude/settings.json`, allow these without prompting:
+默认姿态:**只读自由放行,能改的都问一下。**
-- All `Read`, `Glob`, `Grep` tools
-- `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`, `Bash(git branch)`
-- Project-specific read-only commands (e.g. `Bash(npm test)`, `Bash(pytest)`)
+`.claude/settings.json` 里可以无提示放行:
-Always prompt for:
+- 所有 `Read`、`Glob`、`Grep`
+- `Bash(git status)`、`Bash(git diff)`、`Bash(git log)`、`Bash(git branch)`
+- 项目特定的只读命令(`Bash(npm test)`、`Bash(pytest)` 这类)
-- File `Edit` / `Write` outside the working tree
-- `Bash` with destructive verbs (`rm`, `mv`, `git push`, `git reset --hard`, package installs)
-- Any MCP tool that talks to a remote service
+永远要弹窗确认:
-When you find yourself approving the same prompt over and over, run the
-`fewer-permission-prompts` skill — it scans your transcripts and
-proposes an allowlist.
+- 工作树之外的 `Edit` / `Write`
+- 带破坏动词的 `Bash`(`rm`、`mv`、`git push`、`git reset --hard`、装包)
+- 任何会跟外部服务对话的 MCP 工具
-## Hooks
+如果你发现自己在反复批准同一类提示,跑一下 `fewer-permission-prompts`
+skill——它会扫 transcript 给你列一份允许列表。
-Hooks are how the harness enforces rules automatically — Claude itself
-won't reliably remember a "from now on…" instruction across sessions.
+## Hook(钩子)
-Use hooks for:
+Hook 是让 harness 自动执行规则的方式——AI 自己**不可靠地**记住"以后
+都要 X",跨 session 会忘。
-- Auto-formatting on file edit (Prettier, ruff, gofmt)
-- Blocking edits to protected paths (`.env`, generated files, `dist/`)
-- Auto-running tests after a write to a known test path
-- Notifying on session stop / long-running task completion
+适合用 hook 的事:
-Don't use hooks for:
+- 文件保存后自动格式化(Prettier、ruff、gofmt)
+- 阻止改受保护路径(`.env`、生成文件、`dist/`)
+- 写测试路径后自动跑测试
+- session 结束 / 长任务完成时通知
-- One-off checks ("just remember to do X this week")
-- Anything that depends on Claude's judgment ("only run if it makes sense")
+不适合用 hook 的:
-Configure via the `update-config` skill or edit `.claude/settings.json`
-directly. Document each hook with a one-line comment in the JSON.
+- 一次性检查("这周记得 X 一下")
+- 任何依赖 AI 判断的("觉得有必要就跑")
-## Memory
+通过 `update-config` skill 配置,或者直接编辑 `.claude/settings.json`。
+JSON 里每个 hook 加一行注释说明。
-The harness has a per-machine memory system. Use it for:
+## Memory(记忆)
-- **User**: who you are, your role, your preferences.
-- **Feedback**: corrections you've given Claude that should stick across
- sessions (with the *why*).
-- **Project**: facts about ongoing work that aren't in the code (deadlines,
- stakeholder decisions, why a refactor is happening).
-- **Reference**: pointers to external resources (Linear projects, Grafana
- dashboards, internal wikis).
+Harness 有按机器的记忆系统。用法:
-Don't put memory content in `CLAUDE.md`. CLAUDE.md is project context,
-shared with the team. Memory is personal, per-machine, and lives outside
-the repo.
+- **User**:你是谁、角色、偏好。
+- **Feedback**:你给 AI 的纠正,要跨 session 保留的(带上**为什么**)。
+- **Project**:进行中工作的事实,代码里没写的(截止日期、相关方决策、
+ 为什么要重构)。
+- **Reference**:外部资源指针(Linear 项目、Grafana dashboard、内网 wiki)。
-Don't use memory as a notes app. If it's task-scoped, it goes in a plan or
-PR description.
+不要把 memory 内容塞进 `CLAUDE.md`。CLAUDE.md 是项目上下文,团队共享。
+Memory 是个人的、按机器的,不进仓库。
-## Skills
+不要把 memory 当便签本用。任务级别的东西塞进 plan 或 PR description。
-Skills live in three places:
+## Skill(技能)
-- **User skills** (`~/.claude/skills/`) — installed once, available everywhere
-- **Project skills** (`/.claude/skills/`) — committed, shared with team
-- **Plugin skills** — installed via marketplace
+Skill 在三个地方:
-Promote a workflow to a skill once you've done it the same way three
-times. See `docs/04-skills-and-planning.md` for the catalog.
+- **用户级**(`~/.claude/skills/`)—— 装一次到处可用
+- **项目级**(`/.claude/skills/`)—— 提交进仓库,团队共享
+- **插件**—— 通过 marketplace 安装
-## Sub-agents
+同一个流程做了三次都一样,就提升成 skill。目录见
+[docs/04-skills-and-planning.md](04-skills-and-planning.md)。
-Spawn a sub-agent (via the `Agent` tool) when:
+## Sub-agent(子 agent)
-- The task needs a search across many files and you don't want the
- results in your main context.
-- You want a second, independent read on a design or diff.
-- The work is genuinely parallel (e.g. researching three options).
+什么时候开 sub-agent(用 `Agent` 工具):
-Don't spawn sub-agents for tasks the main agent can do in two tool calls.
-The handoff overhead isn't free.
+- 任务要跨很多文件搜索,又不想把搜索结果塞进主上下文。
+- 想让另一个独立视角再看一遍设计或 diff。
+- 工作真的并行(比如同时调研三个方案)。
-## Sessions
+主 agent 两次工具调用就能搞定的事,别开 sub-agent。交接成本不是免费
+的。
-- One task per session. Open a new session for a new task.
-- If a session is running long and the context bar is filling, finish
- the current step, summarize state into a plan or PR draft, then start
- fresh.
-- Don't use `--continue` to resume a session from yesterday on a new
- topic. The stale context will leak in.
+## Session
+
+- 一个 session 一个任务。新任务开新 session。
+- session 跑长了、上下文条快满了:先收尾当前步骤,把状态总结进 plan
+ 或 PR draft,然后开新 session。
+- 别用 `--continue` 把昨天的 session 拉回来做新主题。陈旧上下文会
+ 渗进来。
diff --git a/docs/03-git-workflow.md b/docs/03-git-workflow.md
index b4fc15c..68b5218 100644
--- a/docs/03-git-workflow.md
+++ b/docs/03-git-workflow.md
@@ -1,35 +1,35 @@
-# 03 — Git workflow
+# 03 — Git 工作流
-Small team, light process. Branches, commits, PRs, review.
+小团队,流程从轻。分支、commit、PR、review、tag。
-## Branches
+## 分支
-- `main` is always shippable. No direct pushes. No exceptions.
-- Feature branches: `/` — e.g. `bai/auth-retry`,
- `bai/eval-agent-rerun`. Lowercase, hyphens, your handle as prefix.
-- Long-lived integration branches: `integration/` — only with
- team agreement.
-- Delete branches after merge. Old branches confuse search.
+- `main` 永远可发。不直接 push,没有例外。
+- 功能分支:`/` —— 比如 `bai/auth-retry`、
+ `bai/eval-agent-rerun`。小写、连字符、你的 handle 做前缀。
+- 长期集成分支:`integration/` —— 团队同意才用。
+- 合并完删分支。老分支会污染搜索结果。
-## Commits
+## Commit
-Format:
+格式:
```
-:
+: <祈使句小结,60 字符以内>
-
+<可选 body —— 写改了什么、为什么,不写怎么改>
```
-- `` is a directory or component, lowercase: `eval-agent`,
- `task_assistant`, `docs`, `git-workflow`.
-- Imperative: "add", "fix", "rename" — not "added" / "adding".
-- Body wraps at ~72 chars. Skip it for trivial commits.
-- One topic per commit. "and" in the summary means split it.
-- AI-assisted commits get the `Co-Authored-By` trailer Claude Code adds
- by default. Don't strip it.
+- `` 是目录或组件,小写:`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 看的内容用英文)。
-Examples:
+例:
```
eval-agent: rerun failed tasks with stable seed
@@ -37,64 +37,55 @@ docs: clarify branch naming in git-workflow
task_assistant: drop unused legacy export path
```
-## Pull requests
+## Pull Request
-- One PR per topic. If you can't describe it in one sentence, it's
- multiple PRs.
-- Title under 70 chars, same shape as a commit summary.
-- Description uses `templates/PR_DESCRIPTION.template.md`.
-- Push to your feature branch with `-u` the first time so it tracks
- remote.
-- Open the PR as soon as you have something runnable, even if it's a
- draft. Review-as-you-go beats review-at-the-end.
+- 一个 PR 一个主题。一句话说不清楚——拆成多个 PR。
+- 标题 70 字符以内,跟 commit 摘要同一形态。
+- Description 用 `templates/PR_DESCRIPTION.template.md`。
+- 第一次 push feature 分支用 `-u`,让它跟踪远端。
+- 有可跑的东西就开 PR,draft 也行。边写边 review 比写完再 review 好。
## Review
-We review every PR before merge, even our own AI-assisted ones.
+每个 PR 都要 review,包括 AI 协作出的,自己也不能跳。
-Reviewer checks:
+Reviewer 检查清单:
-1. Does the description match the diff? If the diff has surprises, ask.
-2. Read every file changed. If a file isn't related to the stated
- topic, ask why it's in the PR.
-3. Run the change locally if it's not obviously correct from reading.
-4. New deps, schema changes, env vars, or auth-touching code → block
- until justified.
-5. Comment on the *least* important issue first; save the merge-blocker
- for last so it's clearly the gate.
+1. Description 跟 diff 对得上吗?diff 有惊喜——发问。
+2. 改的每个文件都看一遍。文件跟主题无关——发问为什么进了 PR。
+3. 改动不是显而易见就本地跑一遍。
+4. 新依赖、schema 变更、env var、动 auth 的代码——讲清楚理由前
+ block。
+5. 评论先发**最不重要**的;merge-blocker 留到最后,让它明显是闸门。
-Author follow-ups:
+作者收尾:
-- Address every comment, even with "agreed, fixed in ".
-- If you disagree, push back in writing. Don't silently ignore.
-- Squash fixup commits before merge if the history is noisy.
+- 每条评论都回应,哪怕只是"同意,已在 修"。
+- 不同意写出来 push back,不要默默忽略。
+- 合并前把噪音 commit 压一下(squash fixup commits)。
-## Merging
+## 合并
-- Squash for feature branches. Merge commits are reserved for
- integration branches.
-- Final squash message follows the commit format above. The PR title is
- usually the right starting point.
-- Delete the branch on merge.
+- Feature 分支用 squash。Merge commit 留给集成分支。
+- 最终 squash message 按 commit 格式写。PR 标题通常就是好起点。
+- 合并完删分支。
-## Tagging (versioning)
+## Tag(版本管理)
-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."
+按日期打 tag:`YYYYMMDD`(比如 `20260520`)。每个 tag 是 `main`
+某一时刻的快照——值得指着说"我们就按这版来"。
-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.
+- 只在 `main` 上打 tag。功能分支打 tag 是 smell。
+- 一天最多一个 tag。同一天再切一个,加 `-N` 后缀:`20260520-2`、
+ `20260520-3`。
+- 用 annotated tag,不用 lightweight。`git tag -a` 加一两句说自上次
+ tag 以来改了什么。
+- Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。
+- Tag commit、push tag、告诉大家 tag 名字——这就是发布。
-Cut a tag:
+切 tag:
```bash
git checkout main
@@ -103,35 +94,33 @@ 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
+git tag --sort=-creatordate # 按时间倒序
+git show 20260520 # 看一个 tag 里有什么
+git log --oneline 20260513..20260520 # 两个 tag 之间改了什么
```
-When to cut a tag:
+什么时候切 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).
+- 本仓库的 docs 改了,队友需要重新读。
+- 加了、删了或重组了 template。
+- 新的约定正式生效(不是还在讨论)。
-When NOT to cut a tag:
+什么时候**不**切 tag:
-- Typo fixes, formatting, broken links → just push to `main`.
-- Drafts under discussion → use a PR, don't tag.
+- 改错别字、调格式、修死链 → 直接 push 到 `main`。
+- 还在讨论的草稿 → 走 PR,不打 tag。
-## What NOT to do
+## 不要做的事
-- No `git push --force` to `main`. Period. To your own branch, only if
- nobody else has pulled it.
-- 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
- files you don't recognize. Stage by name.
+- 不要 `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`。
+ 按文件名加。
diff --git a/docs/04-skills-and-planning.md b/docs/04-skills-and-planning.md
index df50630..7d755d4 100644
--- a/docs/04-skills-and-planning.md
+++ b/docs/04-skills-and-planning.md
@@ -1,112 +1,101 @@
-# 04 — Skills and planning
+# 04 — Skill 与规划
-How we manage the skill catalog and how we plan work as a small team.
+我们怎么管 skill 目录、小团队怎么排活。
-## Skill catalog
+## Skill 目录
-A "skill" is a reusable, named workflow Claude Code can invoke. We keep
-three catalogs:
+"Skill"是 Claude Code 能调用的、命名好的可复用流程。我们维护三份:
-- **Personal** (`~/.claude/skills/`) — private, per developer.
-- **Team** (`/.claude/skills/`) — committed, shared via the project.
-- **Bundled / plugin** — installed from a marketplace.
+- **个人**(`~/.claude/skills/`)—— 私人,每人自己管。
+- **团队**(`/.claude/skills/`)—— 提交进仓库,跟项目共享。
+- **打包 / 插件** —— 从 marketplace 装。
-### When to make a skill
+### 什么时候做 skill
-Promote a workflow to a skill when **all three** are true:
+工作流提升成 skill 要**同时**满足三条:
-1. You've done it the same way three times.
-2. The steps are stable enough to write down.
-3. Someone else on the team would do it the same way if shown.
+1. 你已经用同样的方式做过三次。
+2. 步骤稳定到能写下来。
+3. 别人按你写的也会做出同样的东西。
-If only two are true, leave it as a prompt snippet in your notes.
+只满足两条——留在你的提示词笔记里。
-### Skill design rules
+### Skill 设计规则
-- One skill, one job. Skills that branch on "what does the user want?"
- are two skills.
-- Name the skill as a verb phrase: `review-pr`, `cut-release`,
- `rebuild-fixtures`. Not `pr-helper`.
-- Description (the one-liner the model sees) must say *when to invoke*,
- not what the skill does. The model decides on the *when*.
-- Keep `SKILL.md` under 200 lines. Long skills get broken into stages.
-- Examples beat instructions. Show one good run.
+- 一个 skill 一件事。要分支判断"用户想干什么"——拆成两个。
+- 用动词短语命名:`review-pr`、`cut-release`、`rebuild-fixtures`。
+ 不要 `pr-helper`。
+- Description(模型看的那行字)说**什么时候触发**,不是 skill 干啥。
+ 触发由模型判断。
+- `SKILL.md` 200 行以内。长 skill 拆成阶段。
+- 例子比说明强。给一个跑通的 run。
-### Reviewing skills
+### Skill review
-Treat a new skill like a PR: read it, run it once on a real task, then
-merge. Skills that nobody runs after a month get archived (move to
-`.claude/skills/_archive/`).
+新 skill 当 PR 看:读、在真实任务上跑一次、merge。一个月没人用的
+skill 归档(移到 `.claude/skills/_archive/`)。
-### Active skills (this team)
+### 当前活跃 skill(团队)
-Maintain this list as we go. Drop a one-line description and the path.
+边走边维护。每条一行说明 + 路径。
```
-# Personal recommendations (install with marketplace or copy):
-# anthropic-skills:consolidate-memory — periodic memory cleanup
-# simplify — review changed code for reuse/quality
-# fewer-permission-prompts — propose allowlist from transcripts
-# review — review a pull request
-# security-review — security pass on pending changes
+# 推荐安装的(marketplace 或拷贝):
+# anthropic-skills:consolidate-memory — 周期性 memory 整理
+# simplify — review 改动找复用 / 质量问题
+# fewer-permission-prompts — 从 transcript 提议 allowlist
+# review — review pull request
+# security-review — 对 pending 改动做安全 pass
-# Team skills (in this repo):
-# (none yet — add as we promote workflows)
+# 团队 skill(本仓库):
+# (还没有 —— 提升成 skill 后加进来)
```
-## Planning cadence
+## 规划节奏
-We're 1–3 people. Process should be the lightest thing that keeps us
-aligned. Right now that's:
+我们 1–3 人。流程能保持对齐就够轻。当下做法:
-### Weekly
+### 每周
-- One short async written sync (Mon morning). Each person posts:
- 1. What I shipped last week (one line per item).
- 2. What I'm picking up this week (one line per item).
- 3. What's blocked or unclear (the only section worth reading carefully).
-- 30-minute live call mid-week. Agenda comes from the "blocked or
- unclear" lines.
+- 一次异步书面同步(周一上午)。每人发:
+ 1. 上周交付了什么(每条一行)。
+ 2. 这周准备捡什么(每条一行)。
+ 3. 哪儿卡住或不清楚(**唯一**值得仔细读的部分)。
+- 周中 30 分钟实时会。议题来自上面那条"卡住或不清楚"。
-### Per-task
+### 每个任务
-Before starting work that will take more than ~half a day:
+要超过半天的活,开工前:
-1. Write a 5-line spec: *Goal / Why / Done when / Out of scope / Risks*.
-2. Drop it in the PR description (draft PR is fine) **before** writing
- code.
-3. If Claude is going to do most of the typing, the spec is also the
- prompt — paste it in.
+1. 写 5 行 spec:*目标 / 为什么 / 完成标准 / 范围外 / 风险*。
+2. 在 PR description 里贴上(draft PR 也行),**写代码前**。
+3. AI 要替你打字的话,这段 spec 就是提示词——直接喂进去。
-After finishing:
+收尾:
-1. PR description updated to match what actually shipped.
-2. Anything you learned that future-you would want goes into Claude
- memory (feedback / project type) — see `docs/02-claude-code.md`.
+1. PR description 更新到跟实际交付一致。
+2. 学到的、未来你想看到的,进 Claude memory(feedback / project 类型)
+ —— 见 [docs/02-claude-code.md](02-claude-code.md)。
-### Per-quarter
+### 每季度
-One half-day to:
+留半天:
-- Re-read this `team-guide` repo. Open PRs for what's stale.
-- Review the skill catalog. Archive what we don't use.
-- Run `consolidate-memory` against personal memory files.
+- 重读本仓库。过期的开 PR 改。
+- 重审 skill 目录。不用的归档。
+- 跑 `consolidate-memory` 整理个人 memory 文件。
-## Project structure
+## 项目结构
-When starting a new project under this workspace:
+工作区下开新项目:
-1. Copy `templates/README.md.template` and `templates/CLAUDE.md.template`.
-2. `git init` immediately, even if the project is throwaway. Throwaway
- projects survive longer than you expect.
-3. First commit: scaffolding only, no real code. Makes future `git log`
- readable.
-4. Add the project to the workspace `README` (when we have one) so it's
- discoverable.
+1. 复制 `templates/README.md.template` 和 `templates/CLAUDE.md.template`。
+2. 立刻 `git init`,哪怕项目是一次性的。一次性项目活得比你想的久。
+3. 第一个 commit 只放脚手架,没有真实代码。让 `git log` 后续好读。
+4. 把项目加进工作区 README(有了之后),让别人能发现。
-## What planning is *not*
+## 规划**不是**
-- It's not Jira tickets. We don't need a board for two people.
-- It's not Gantt charts. If we need one, we're building the wrong thing.
-- It's not status theater. The Monday post is for spotting blocks, not
- for proving you worked.
+- 不是 Jira ticket。两个人不需要看板。
+- 不是 Gantt 图。需要 Gantt 说明在做错的东西。
+- 不是状态秀。周一帖是为了发现卡点,不是证明你干了活。
diff --git a/docs/05-code-style.md b/docs/05-code-style.md
index ed1d199..84325ef 100644
--- a/docs/05-code-style.md
+++ b/docs/05-code-style.md
@@ -1,111 +1,96 @@
-# 05 — Code & deliverable style
+# 05 — 代码与产出风格
-Naming, comments, structure. Same rules apply whether a human or Claude
-typed the code.
+命名、注释、结构。不论是人写的还是 AI 写的代码,都按这套来。
-## Naming
+## 命名
-- **Files** — lowercase, hyphens for docs (`git-workflow.md`),
- underscores for Python (`task_runner.py`), kebab for JS/TS where the
- ecosystem prefers it. Match the surrounding project.
-- **Functions** — verb phrases. `loadConfig`, not `config`. `runTask`,
- not `taskRunner`.
-- **Variables** — say what they are, not their type. `users`, not
- `userArray`. `retryCount`, not `n`.
-- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
-- **Constants** — `UPPER_SNAKE_CASE` only when truly module-level
- constants. Inside functions, just use a normal `const`.
-- **No abbreviations** unless they're a domain term. `database`, not
- `db`. `request`, not `req`. (`req`/`res` in Express handlers is fine —
- domain convention.)
+- **文件** —— 小写。文档用连字符(`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` 是领域约定,可以。)
-## Comments
+## 注释
-Default to none. A comment is justified when **all** are true:
+默认不写。要写注释,**全部**条件成立:
-- The *why* is non-obvious from the code.
-- A future reader would otherwise misread the code.
-- The code itself can't be made clearer (rename, extract, restructure).
+- "为什么"从代码里看不出来。
+- 未来读代码的人不写注释会读错。
+- 代码本身改不清晰(重命名、抽函数、重组都试过)。
-Don't write:
+不要写:
-- `// increment counter` next to `counter++`
-- `// added for the auth refactor` — belongs in the commit message
-- Block comments restating function signatures
-- TODOs without an owner or a date — they rot. Either fix it now, file
- an issue, or delete the comment.
+- `// increment counter` 紧挨着 `counter++`
+- `// added for the auth refactor` —— 这话该在 commit message 里
+- 一大段 docstring 只是把签名复述一遍
+- 没有 owner 没有日期的 TODO —— 它们会烂掉。要么现在修,要么开
+ issue,要么删了。
-Do write:
+可以写:
-- One-liners explaining a non-obvious workaround, with the *why*.
-- A `# NOTE:` when behavior would surprise a reader.
-- Module headers only when a file does something the directory layout
- doesn't already explain.
+- 一行解释一个非显而易见的 workaround,带上**为什么**。
+- `# NOTE:` 标注会让读者意外的行为。
+- 文件头注释,仅限于这个文件做的事目录结构没说清楚。
-## File structure
+## 文件结构
-- One concept per file. If you can't summarize the file in one sentence,
- split it.
-- Keep tests next to the code, not in a parallel tree, unless the
- project already does the parallel tree.
-- Generated files go in `dist/`, `build/`, or similar — and into
- `.gitignore`. Never edit a generated file.
-- Lockfiles are checked in. Always.
+- 一个文件一个概念。一句话说不清这个文件干啥——拆。
+- 测试文件挨着代码放,除非项目本来就是平行测试树。
+- 生成文件进 `dist/` / `build/` 这类目录,进 `.gitignore`。永远
+ 不改生成文件。
+- Lockfile 必须 commit,永远。
-## Errors
+## 错误
-- Fail loudly at boundaries (user input, external APIs, file I/O).
-- Don't `try/except` to silence errors. If you catch, you handle.
-- Internal functions trust their callers. Don't validate the same input
- three layers deep.
-- Logged errors include enough context to debug from logs alone — what
- was being attempted, which inputs, which path.
+- 在边界处(用户输入、外部 API、文件 I/O)大声失败。
+- 不要 `try/except` 吞错。捕了就处理。
+- 内部函数信任调用方,不要在三层深度上重复校验同一个输入。
+- 日志里的错要带够上下文,光看日志能调试——做的什么操作、输入是
+ 什么、走的哪条路径。
-## Tests
+## 测试
-- Test the behavior, not the implementation. If a refactor that
- preserves behavior breaks a test, the test was wrong.
-- One assertion per test, ideally. "Tests that test many things at once
- fail unhelpfully."
-- Fixtures live next to the tests that use them.
-- Slow / flaky tests get marked or quarantined, not silently retried.
-- New code without a test is incomplete unless the project genuinely
- has no test infrastructure (rare, and a bug in itself).
+- 测行为,不测实现。一个保留行为的重构把测试搞挂了——是测试错。
+- 一个测试一个断言为佳。"啥都测的测试,挂了你不知道是哪一个挂了。"
+- Fixture 和用它的测试放一起。
+- 慢 / flaky 的测试加标记或隔离,不要默默重试。
+- 没测试的新代码就是没写完——除非项目真的没有测试基础设施
+ (罕见,而且这本身是个 bug)。
-## READMEs
+## README
-Every repo has a `README.md`. It answers, in order:
+每个仓库都要有 `README.md`。按这个顺序回答:
-1. **What is this?** One paragraph.
-2. **How do I run it?** Bash blocks for setup, run, test.
-3. **How do I develop on it?** Where the code lives, what the conventions
- are.
-4. **Where does the data come from / go to?** Only if non-obvious.
-5. **Pointers.** Related repos, dashboards, docs.
+1. **这是什么?** 一段话。
+2. **怎么跑?** Setup / run / test 的 bash 块。
+3. **怎么开发?** 代码在哪,约定是什么。
+4. **数据从哪来 / 去哪?** 仅当不显然才写。
+5. **指针。** 关联仓库、dashboard、文档。
-Use `templates/README.md.template`. If the README is shorter than the
-template, that's fine — delete the unused sections.
+用 `templates/README.md.template`。如果你的 README 比模板短,没问题
+——把没用的 section 删掉。
-## Deliverables (task packages, datasets, exports)
+## 交付物(任务包、数据集、导出)
-When we ship a deliverable to a partner or downstream consumer:
+给伙伴或下游交付时:
-1. Versioned filename: `-v.` or `-.`.
- Pick one convention per project and stick to it.
-2. Ships with a `README` describing schema, generation date, known
- limitations.
-3. Ships with a verification report (counts, checksums, sanity checks)
- in the same archive.
-4. Exact commit hash that produced it goes in the README.
+1. 文件名带版本:`-v.` 或 `-.`。
+ 一个项目一种约定,定了别变。
+2. 配 `README` 写明 schema、生成日期、已知限制。
+3. 配验证报告(计数、checksum、合理性检查),跟交付物一起打包。
+4. 生成它的 commit hash 写进 README。
-See `docs/06-handoff.md` for the full checklist.
+完整 checklist 见 [docs/06-handoff.md](06-handoff.md)。
-## What NOT to do
+## 不要做的事
-- Don't introduce a third way to do something we already do two ways.
- Pick one and migrate.
-- Don't add config options "for flexibility" without a real use case.
- YAGNI.
-- Don't refactor unrelated code in a feature PR. Open a separate PR.
-- Don't optimize before measuring. "It might be slow" is not a
- measurement.
+- 不要引入第三种做某件事的方式——已经有两种了。挑一种统一。
+- 不要"为了灵活性"加配置开关,没有真实用例就别加。YAGNI。
+- 不要在功能 PR 里顺手重构无关代码。开新 PR。
+- 不要没量就先优化。"可能慢"不是测量结果。
diff --git a/docs/06-handoff.md b/docs/06-handoff.md
index d2f7a16..73a442b 100644
--- a/docs/06-handoff.md
+++ b/docs/06-handoff.md
@@ -1,41 +1,37 @@
-# 06 — Handoff
+# 06 — Handoff(交接)
-Task packages, deliverables, and how we hand work between team members
-or to external consumers.
+任务包、交付物、团队成员之间或对外部消费方的交接。
-## Why this matters
+## 为什么这事重要
-Handoff failures cost more than the original work. A package that's
-"obviously how it works" to the author is a half-day of confusion for
-the recipient. Treat handoff as part of the deliverable, not as
-afterthought packaging.
+交接出问题的成本比原工作高。作者觉得"显然就是这么用的"的包,到接收方
+手里是半天的迷茫。把交接当**交付物的一部分**对待,不是事后包装。
-## Two kinds of handoff
+## 两种 handoff
-1. **Internal** — passing work to another team member (or future-you).
- Usually a branch, a PR, or a half-finished prototype.
-2. **External** — shipping a versioned artifact to a partner, customer,
- or downstream pipeline. Usually a zip, a dataset, or a release.
+1. **内部** —— 把工作交给队友(或未来的你)。通常是分支、PR、半成品
+ 原型。
+2. **外部** —— 给伙伴、客户或下游 pipeline 发版本化产物。通常是 zip、
+ 数据集、release。
-Both use the checklist in `templates/HANDOFF_CHECKLIST.template.md`. The
-external case has a higher bar.
+两种都用 `templates/HANDOFF_CHECKLIST.template.md`。外部的标准更高。
-## Task packages
+## 任务包
-When we ship a task package (e.g. `praxis-sample-5.zip`,
-`task-assistant-v0.2-handoff-*.zip`), it must contain:
+我们发的任务包(比如 `praxis-sample-5.zip`、
+`task-assistant-v0.2-handoff-*.zip`)必须包含:
```
/
-├── README.md ← what this is, who it's for, how to use it
-├── CHANGELOG.md ← what changed since the last version
-├── VERIFICATION.md ← counts, checksums, sanity checks
-├── manifest.json ← machine-readable metadata
-├── data/ ← the actual deliverable
-└── scripts/ ← only what's needed to use the package
+├── README.md ← 这是什么、给谁用、怎么用
+├── CHANGELOG.md ← 自上一版改了什么
+├── VERIFICATION.md ← 计数、checksum、合理性检查
+├── manifest.json ← 机器可读的元数据
+├── data/ ← 真正的交付物
+└── scripts/ ← 用这个包必须的脚本
```
-`manifest.json` minimum fields:
+`manifest.json` 至少要有:
```json
{
@@ -49,73 +45,59 @@ When we ship a task package (e.g. `praxis-sample-5.zip`,
}
```
-If you can't fill a field, leave it as `null` and explain in the README.
-Never make one up.
+填不出的字段写 `null`,在 README 里解释。**永远不要瞎编**。
-## Internal handoff (branch / PR)
+## 内部 handoff(分支 / PR)
-Before handing off:
+交出去之前:
-- PR description is current. The summary describes what shipped, not
- what was attempted.
-- The "test plan" section in the PR template is filled in honestly. If
- you didn't test something, say so — don't bury it.
-- Any AI-assisted decisions that surprised you go in a `## Notes for
- reviewer` section. "Claude tried X first, that didn't work because Y,
- here's the working approach" saves the reviewer a re-derivation.
-- Local-only state (env vars, scratch data) is documented or scripted.
- "Works on my machine" is not a handoff.
+- PR description 是最新的。Summary 写实际交付了什么,不是尝试过什么。
+- PR template 里的 "test plan" 老老实实填。没测就说没测——别埋。
+- AI 协作中让你意外的决策放进 `## Notes for reviewer`。"AI 先试了 X
+ 不行因为 Y,最后用了 Z"——省 reviewer 重推一遍。
+- 本地状态(env var、临时数据)要文档化或脚本化。"在我机器上能跑"
+ 不算交接。
-The recipient should be able to:
+接收方应该能:
-1. `git checkout` the branch
-2. Read the PR description
-3. Run the test plan
-4. Form an opinion
+1. `git checkout` 这个分支
+2. 读 PR description
+3. 跑 test plan
+4. 形成自己的判断
-— without messaging you. If they have to message you, the handoff is
-incomplete.
+—— **不用问你**。如果接收方还要私聊你,handoff 就是不完整的。
-## External handoff (versioned artifact)
+## 外部 handoff(版本化产物)
-Higher bar. In addition to the task package contents above:
+标准更高。除上面任务包内容外:
-- **Reproducibility.** Someone with access to the source repo can
- rebuild the artifact from the commit hash in `manifest.json`. Test
- this at least once before the first release.
-- **Verification report.** A machine-checkable report (JSON or
- similar) showing the artifact passed our pre-ship checks. Include
- what was checked and the result.
-- **Provenance.** If the artifact was generated using AI assistance,
- note the model and any human-in-the-loop steps. Not for ceremony —
- for debugging when something looks wrong six months from now.
-- **License & attribution.** Even for internal partners. Be explicit
- about what they can and can't do with the data.
+- **可重现。** 有源码访问的人能从 `manifest.json` 里的 commit hash
+ 重建产物。第一次发布前测一遍。
+- **验证报告。** 一份机器可读(JSON 之类)的报告,记录预发检查的
+ 通过情况。写清楚检查了什么、结果是什么。
+- **来源(provenance)。** AI 协助生成的,写明用的哪个模型、人工
+ 审核步骤是什么。不是为了仪式感——是为了半年后产物有问题时好查。
+- **License 与署名。** 内部伙伴也要写。明确他们能用、不能用。
-## What NOT to ship
+## 不要发的东西
-- Files larger than ~500 MB without a conversation about delivery
- channel.
-- Anything containing real PII unless that was explicitly the deal.
-- `.env`, secrets, API keys, internal hostnames.
-- "Final final v3" filenames. Use the version field. If it's `final`,
- it's `v1.0`.
-- A package without a README. Even a one-line README beats none.
+- 没聊过传输渠道的 ~500 MB 以上文件。
+- 含真实 PII 的内容——除非交付协议里就明确包含。
+- `.env`、密钥、API key、内部主机名。
+- "final final v3" 命名。用 version 字段。要是 final,那就是 `v1.0`。
+- 没有 README 的包。一行 README 也比没有强。
-## Receiving a handoff
+## 收到 handoff 时
-When you're on the receiving end:
+你是接收方:
-1. Read the README first, fully. Resist the urge to start running
- scripts.
-2. Run the verification report. If it doesn't pass, stop and message
- the sender before doing anything else.
-3. Note any surprise — naming, missing files, version mismatch — and
- send it back to the sender within a day. Drift gets worse with
- silence.
+1. 先**完整读** README。忍住直接跑脚本的冲动。
+2. 跑一遍验证报告。不通过——停下来联系发送方再做任何事。
+3. 任何意外(命名、缺文件、版本不对)一天内反馈给发送方。drift 不
+ 反馈只会越来越歪。
-## Templates
+## 模板
-- `templates/HANDOFF_CHECKLIST.template.md` — fill out per handoff,
- ships in the package.
-- `templates/PR_DESCRIPTION.template.md` — for internal handoff via PR.
+- `templates/HANDOFF_CHECKLIST.template.md` —— 每次交接填一份,跟
+ 包一起发。
+- `templates/PR_DESCRIPTION.template.md` —— 内部 handoff 走 PR 用。
diff --git a/docs/07-codex.md b/docs/07-codex.md
new file mode 100644
index 0000000..49ae299
--- /dev/null
+++ b/docs/07-codex.md
@@ -0,0 +1,114 @@
+# 07 — Codex
+
+我们怎么在团队里用 Codex(CLI 与 IDE 集成),以及 `AGENTS.md` 怎么写。
+
+## 为什么要规范
+
+Codex 不读 `CLAUDE.md`。Claude Code 默认不读 `AGENTS.md`。两个工具在
+同一个仓库里干活,看的是不同的"项目说明书"。如果只写一份,另一边就
+是裸奔。
+
+我们的做法:**两份都写,内容保持同步**。哪边的工具进来读哪边的文件。
+
+## 文件分工
+
+```
+/
+├── 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 ""`(一次性
+ 任务)。在仓库根目录启动,让它能找到 `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`。
diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template
new file mode 100644
index 0000000..e72fe2b
--- /dev/null
+++ b/templates/AGENTS.md.template
@@ -0,0 +1,69 @@
+# AGENTS.md —
+
+
+
+## Project
+
+
+
+## Run it
+
+```bash
+# install
+
+
+# run
+
+
+# test
+
+
+# lint / typecheck
+
+```
+
+## Architecture
+
+
+
+Key files:
+
+- `` —
+- `` —
+
+## Conventions specific to this repo
+
+
+
+## Language policy
+
+
+
+- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
+ in Chinese.
+- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
+ English.
+- Commit messages, PR titles, branch names, tag annotations: English.
+
+## Don'ts
+
+
+
+- Don't <…>
+- Don't <…>
+
+## External resources
+
+
+
+## Sync
+
+When you edit this file, also update `CLAUDE.md` (and vice versa). The
+two files describe the same project to different tools.
diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template
index 3246485..fa397dc 100644
--- a/templates/CLAUDE.md.template
+++ b/templates/CLAUDE.md.template
@@ -2,10 +2,11 @@
-## What this project is
+## Project
@@ -40,9 +41,19 @@ Key files:
+## Language policy
+
+
+
+- Human-facing docs (README, `docs/*.md`, human-fillable templates) are
+ in Chinese.
+- AI-facing files (`CLAUDE.md`, `AGENTS.md`, AI-only templates) are in
+ English.
+- Commit messages, PR titles, branch names, tag annotations: English.
+
## Don'ts
-
- Don't <…>
@@ -51,3 +62,8 @@ One line each. Add to this list as you discover them.>
## External resources
+
+## Sync
+
+When you edit this file, also update `AGENTS.md` (and vice versa). The
+two files describe the same project to different tools.
diff --git a/templates/HANDOFF_CHECKLIST.template.md b/templates/HANDOFF_CHECKLIST.template.md
index 7e7b166..351a8f7 100644
--- a/templates/HANDOFF_CHECKLIST.template.md
+++ b/templates/HANDOFF_CHECKLIST.template.md
@@ -1,71 +1,65 @@
-# Handoff checklist —
+# Handoff 清单 — <包名或分支名>
-## Identity
+## 身份信息
-- **Name**:
-- **Version**:
-- **Generated at**:
-- **Source repo**:
-- **Source commit**:
-- **Author / handoff owner**:
-- **Recipient**:
+- **名称**:<包名或分支名>
+- **版本**:<比如 v0.5.0 或 commit sha 或 tag 比如 20260520>
+- **生成时间**:
+- **源仓库**:
+- **源 commit**:
+- **作者 / handoff owner**:
+- **接收方**:
-## Contents
+## 内容物
-- [ ] `README.md` — describes what this is, how to use it
-- [ ] `CHANGELOG.md` — what's different from the previous version (or
- "first release")
-- [ ] `manifest.json` — machine-readable metadata, all fields filled or
- explicitly null
-- [ ] `VERIFICATION.md` — what we checked, what passed
-- [ ] Data / artifacts — the actual deliverable
-- [ ] Scripts — only what's needed to use the package
+- [ ] `README.md` —— 这是什么、怎么用
+- [ ] `CHANGELOG.md` —— 跟上一版的差异(首发就写"first release")
+- [ ] `manifest.json` —— 机器可读元数据,所有字段都填了或显式 null
+- [ ] `VERIFICATION.md` —— 检查了什么、结果如何
+- [ ] 数据 / 产物 —— 真正的交付物
+- [ ] 脚本 —— 仅限于使用本包必须的脚本
-## Verification
+## 验证
-- [ ] Record / file counts match expected
-- [ ] Checksums computed and recorded
-- [ ] Sanity checks pass (list them)
-- [ ] No secrets, `.env`, or credentials included
-- [ ] No PII unless explicitly part of the deliverable
-- [ ] Total size reasonable for delivery channel
+- [ ] 记录数 / 文件数与预期一致
+- [ ] Checksum 已计算并记录
+- [ ] 合理性检查通过(列出来)
+- [ ] 不含密钥、`.env`、credential
+- [ ] 不含 PII(除非交付协议里就明确包含)
+- [ ] 总大小在传输渠道可接受范围
-Verification report path: ``
+验证报告路径:``
-## Reproducibility
+## 可重现性
-- [ ] Confirmed someone with repo access can rebuild from
- `source_commit` (note who tested this and when)
-- [ ] Build / generation command documented in `README.md`
-- [ ] External dependencies pinned to versions
+- [ ] 已确认有源仓库访问的人能从 `source_commit` 重建产物(写明
+ 谁测的、什么时候测的)
+- [ ] 构建 / 生成命令写在 `README.md` 里
+- [ ] 外部依赖锁版本
-## Provenance (if AI-assisted)
+## 来源(AI 协助生成时填)
-- Model used:
-- Human-in-the-loop steps:
-- Notable AI-assisted decisions:
+- 使用的模型:<比如 claude-opus-4-7、gpt-5-codex>
+- 人工审核步骤:<人审 / 批准了哪些部分>
+- 值得标注的 AI 决策:<半年后产物有问题时会想知道的事>
-## Known limitations
+## 已知限制
-
+<不能用的场景、未覆盖的边界、本版没赶上的后续。具体写。"在我机器
+上能跑"不是限制——是发布前要修的问题。>
- <…>
- <…>
-## Recipient instructions
+## 给接收方的说明
-- [ ] Read `README.md` first
-- [ ] Run the verification report — if it fails, stop and contact the
- sender
-- [ ] Confirm receipt within
-- [ ] Report any surprises (missing files, version mismatch, naming)
- back to the sender within
+- [ ] 先读 `README.md`
+- [ ] 跑验证报告 —— 不通过就停下来联系发送方
+- [ ] 内确认收到
+- [ ] 任何意外(缺文件、版本不对、命名异常)内反馈给发送方
diff --git a/templates/PR_DESCRIPTION.template.md b/templates/PR_DESCRIPTION.template.md
index 10a6803..b0e6d16 100644
--- a/templates/PR_DESCRIPTION.template.md
+++ b/templates/PR_DESCRIPTION.template.md
@@ -1,52 +1,49 @@
-## Summary
+## Summary(小结)
-
+<一句话说清这个 PR 干了什么。需要的话再加 1–3 条 bullet。>
-
-
-## Why
+## Why(为什么)
-
+<动机。解决什么问题、落实什么决策、修哪个 bug。如果挂着 issue
+或者之前的讨论,链上来。>
-## What changed
+## What changed(改了什么)
-
+<列出实际改动,跨多个区域时按区域分组。写事实就行——diff 是真相
+来源,这只是地图。>
-- `` —
-- `` —
+- `<文件或区域>` — <改动>
+- `<文件或区域>` — <改动>
-## Test plan
+## Test plan(测试方案)
-
+<勾选式 checklist。做了的勾 `[x]`,没做的留 `[ ]` 并在下面解释为什么。
+诚实——"没测"可以接受,"声称测了但没测"不行。>
-- [ ] Unit tests pass locally (``)
-- [ ] Lint / typecheck pass (``)
-- [ ]
-- [ ]
+- [ ] 单元测试本地通过(``)
+- [ ] Lint / typecheck 通过(``)
+- [ ] <功能特定的检查>
+- [ ] <功能特定的检查>
-## Out of scope
+## Out of scope(范围外)
-
+<你注意到但**显式选择不在这个 PR 修**的东西。帮 reviewer 不要在这些
+点上提出来。>
-## Notes for reviewer
+## Notes for reviewer(给 reviewer 的提示)
-
+<让你意外的地方、值得标注的 AI 协作决策、走过的捷径,或者"我考虑
+过 X 但选了 Y 因为 Z"。没什么可写就删掉这一节。>
---
-🤖 AI-assisted with Claude Code.
+🤖 AI 协助完成(Claude Code / Codex)。
diff --git a/templates/README.md.template b/templates/README.md.template
index b0f2f9f..9c03cc4 100644
--- a/templates/README.md.template
+++ b/templates/README.md.template
@@ -1,62 +1,62 @@
-#
+# <项目名>
-
+<一句话。这是什么,用大白话写。>
-## What it does
+## 这玩意儿干啥的
-
+<一段话。比 tagline 多点细节。谁会用、解决什么问题、明确**不**做
+什么。>
-## Quick start
+## 快速上手
```bash
# clone
git clone
cd
-# install
+# 安装
-# run
+# 跑起来
```
-Expected output:
+预期输出:
```
-
+<几行用户应该看到的内容>
```
-## Development
+## 开发
```bash
-# tests
+# 测试
# lint / typecheck
-# format
+# 格式化
```
-Code lives in ``. Tests live in ``. See [docs/](docs/) for
-deeper architecture notes (or delete this line if there are none).
+代码在 ``。测试在 ``。架构细节看 [docs/](docs/)(没有就
+删掉这行)。
-## Configuration
+## 配置
-
+
-## Data sources / outputs
+## 数据来源 / 流向
-
+<仅当不显然时写。输入从哪来,输出到哪去。>
-## Related
+## 相关链接
--
--
+- <链接>
+- <链接>
## License
-
+