Jason-chen-coder · Jason-chen-coder · May 14, 2026 · May 12, 2026 · May 13, 2026
diff --git a/AGENTS.md.template b/AGENTS.md.template
@@ -0,0 +1,80 @@
+# AGENTS.md — Team-level Always-On Guidelines
+
+> **这是一份模板文件(`AGENTS.md.template`)。**
+>
+> 使用 Codex 时,把本文件复制到团队项目根目录并重命名为 `AGENTS.md`,再按 `<!-- team:fill -->` 标记填团队真实情况。
+>
+> 本文件是团队级**永远在上下文里**的工程约定。skill 是「场景触发」的检查点,本文件是「贯穿所有任务」的行为底色。
+
+---
+
+## 1. 不可破的硬规则
+
+- **不要在没有显式授权的情况下** `git push --force` / `git push --force-with-lease` 到 protected 分支。
+- **不要新增运行时依赖**(npm / pip / pub / cargo 等)未经讨论。如果需要,在 PR 描述里独立说明原因。
+- **不要写裸 secret / API key / token / 个人路径** 到任何文件。`.env.example` 用占位符。
+- **不要修改与本任务无关的代码**。
+- **不要用 LLM 生成的代码替换现有的、有 git blame 的代码而不说明**。
+
+---
+
+## 2. Workflow 约定
+
+### Clean-tree worktree checkpoint
+
+- 第一次写文件前,如果 `git status --short` 为空,且任务预计会修改代码 / 多文件规则 / 配置 / 测试,先询问用户是否创建独立 worktree。
+- 可跳过询问的场景:纯 typo / 单文件小文档 / 用户已明确说「直接在当前目录改」/ 当前已经在专用 worktree 或任务分支内。
+- 当前分支是 `main` / `master` / `release/*` 时,默认推荐创建 worktree;如果用户拒绝,至少提醒当前目录会被直接修改。
+- 当前 working tree 已经 dirty 时,不要为当前任务从脏目录直接建 worktree;先说明已有改动,避免混入用户改动。
+
+### Worktree 创建规范
+
+- 分支命名跟随团队分支规则;AI 默认使用 `codex/<short-slug>`,例如 `codex/user-export`、`codex/fix-cart-overflow`。
+- worktree 目录放在当前仓库的兄弟目录,命名为 `<repo>-<short-slug>`,只用 lowercase kebab-case,不加空格。
+- 推荐命令:`git worktree add -b codex/<short-slug> ../<repo>-<short-slug>`。
+- 创建后在新 worktree 内确认 `git status --short` 为空,再开始写文件。
+- 合并或放弃后清理:`git worktree remove ../<repo>-<short-slug>`;若分支已废弃,再删除对应分支。
+
+### 设计前置(skill 工具链)
+<!-- team:fill — 团队是否强制以下流程,leader 拍板 -->
+
+- 复杂新功能先过 `dev-spec` 和 `dev-plan --deliberate`。
+- 常规 bug 走 `dev-fix`;生产事故 / 间歇性 / 跨系统 bug 走 `dev-fix --deep`。
+- commit 前过 `dev-code-review`;仅当用户明确跳过 review 时才用 `dev-commit-writer`。
+- 不知道下一步时跑 `dev-workflow`,它只指路不调起其他 skill。
+
+### 分支
+<!-- team:fill -->
+
+- 默认分支:`main`(或 `master`)。
+- 功能分支命名:`<type>/<short-desc>`;AI 默认分支前缀:`codex/`。
+- 长期分支仅 `main`、`release/*`。其他都是 short-lived。
+
+### Commit
+
+- 单 commit 单一意图。
+- 风格跟随仓库 `git log --oneline -20`;无明显风格时退回 conventional commits。
+- subject ≤ 72 chars,祈使语气,不加句号。
+
+---
+
+## 3. AI 协作专属护栏
+
+- 写完先自己读一遍,进入 PR 前能解释每一行。
+- 不接受不能解释的 API / 库 / 模式。
+- PR 描述里标注 LLM 协作程度,例如 `[AI-assisted]`。
+- 大段 LLM 生成的代码必须有测试。
+
+---
+
+## 4. 当 skill 与 AGENTS.md 冲突
+
+- skill 局部规则 > AGENTS.md > dev-baseline。
+- 若发现 skill 输出与 AGENTS.md 冲突,以 AGENTS.md 为准,并在 PR 里反馈。
+
+---
+
+## 5. 当用户指令与本文件冲突
+
+- 优先服从用户当下指令,但先一句话提示冲突并请求确认。
+- 用户确认后照办,但在 commit / PR 描述里记录例外原因。
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,7 +12,8 @@
 ## [Unreleased]
 
 ### Added
-- *(占位:下一版要发的东西先记在这里。)*
+- **Clean-tree worktree checkpoint**:在 `CLAUDE.md.template` / `AGENTS.md.template` / `dev-workflow` / `dev-plan` / `dev-fix` 中加入编码前 worktree 检查与创建规范。AI 在 clean tree 且即将进行非平凡代码/多文件改动前,应先询问是否创建独立 worktree;默认分支命名 `codex/<short-slug>`,目录命名 `<repo>-<short-slug>`。
+- **`AGENTS.md.template`**:新增 Codex 面向的团队 always-on 规则模板,与 `CLAUDE.md.template` 保持核心 workflow 护栏一致。
 
 ---
 

diff --git a/CLAUDE.md.template b/CLAUDE.md.template
@@ -42,7 +42,7 @@
 **新功能路径**:
 - **复杂改动**(跨 ≥ 3 模块 / 涉及鉴权 / 支付 / 数据迁移 / 公开 API breakage / PII 处理)**必须**先过 `dev-spec`(对齐需求)和 `dev-plan --deliberate`(获得 Critic 共识 + Pre-mortem + Expanded test plan),不得直接编码。
 - **常规改动**(单模块 / 中等复杂)建议先过 `dev-spec`,plan 可省略;不强制。
-- **一句话改动 / hotfix** 跳过 spec 和 plan,直接编码,但 commit 前**必须**过 `dev-commit-review`。
+- **一句话改动 / hotfix** 跳过 spec 和 plan,直接编码,但 commit 前**必须**过 `dev-code-review`。
 
 **Bug 路径**:
 - **生产事故 / 间歇性 / 跨系统 bug** **必须**走 `dev-fix --deep`(强制 3-5 hypothesis + 反向 call-stack 追溯 + tagged instrument + Pattern analysis + 完整 RCA)。
@@ -52,6 +52,19 @@
 **入口推荐器**:
 - 不知道走哪条路径 / 卡在某 phase / 失败恢复时,跑 `dev-workflow`(默认 / `--status` / `--next` / `--recover`),它**只指路不调起任何 skill**,用户仍自己执行。
 
+**Clean-tree worktree checkpoint**:
+- 第一次写文件前,如果 `git status --short` 为空,且任务预计会修改代码 / 多文件规则 / 配置 / 测试,先询问用户是否创建独立 worktree。不要在用户未确认时直接开始改。
+- 可跳过询问的场景:纯 typo / 单文件小文档 / 用户已明确说「直接在当前目录改」/ 当前已经在专用 worktree 或任务分支内。
+- 当前分支是 `main` / `master` / `release/*` 时,默认推荐创建 worktree;如果用户拒绝,至少提醒当前目录会被直接修改。
+- 当前 working tree 已经 dirty 时,不要为当前任务从脏目录直接建 worktree;先说明已有改动,避免混入用户改动,由用户决定继续当前目录 / 清理 / 另建基于 HEAD 的 worktree。
+
+**Worktree 创建规范**:
+- 分支命名跟随团队分支规则;AI 默认使用 `codex/<short-slug>`,例如 `codex/user-export`、`codex/fix-cart-overflow`。
+- worktree 目录放在当前仓库的兄弟目录,命名为 `<repo>-<short-slug>`,只用 lowercase kebab-case,不加空格。
+- 推荐命令:`git worktree add -b codex/<short-slug> ../<repo>-<short-slug>`。
+- 创建后在新 worktree 内确认 `git status --short` 为空,再开始写文件。
+- 合并或放弃后清理:`git worktree remove ../<repo>-<short-slug>`;若分支已废弃,再删除对应分支。
+
 **中间产物路径**(consumer 项目根的 `.claude/artifacts/` 下):
 - `designs/<feature>.md`(dev-spec)
 - `plans/<feature>.md`(dev-plan)
@@ -65,7 +78,7 @@
 - 长期分支:仅 `main`、`release/*`(若有)。其他都是 short-lived。
 
 ### Commit
-- 单 commit 单一意图(参见 dev-commit-review 的 surgical 检查)。
+- 单 commit 单一意图(参见 dev-code-review 的 surgical 检查)。
 - 风格跟随仓库 `git log --oneline -20` 的样式;无明显风格时退回 conventional commits。
 - subject ≤ 72 chars,祈使语气,不加句号。
 
@@ -109,7 +122,7 @@
 ### 日志
 <!-- team:fill -->
 - 统一 logger:`<例如 pino / structlog / logger 项目 wrapper>`
-- 禁止 `console.log` / `print` / `fmt.Println` 进入主分支(dev-commit-review 会拦)。
+- 禁止 `console.log` / `print` / `fmt.Println` 进入主分支(dev-code-review 会拦)。
 - 日志级别约定:`<error/warn/info/debug 各自的判定标准>`
 
 ### 配置 / Feature flag

diff --git a/README.md b/README.md
@@ -37,28 +37,46 @@ Claude Code 和 Codex 的安装方式**不一样**:
 - Claude Code 走本仓库的 `.claude-plugin/` manifest,用 `/plugin marketplace add` + `/plugin install`。
 - Codex 目前先把 `skills/*` 安装到 `$CODEX_HOME/skills`(默认 `~/.codex/skills`)。等本仓库补齐 `.codex-plugin/` 后,会再提供 Codex plugin 方式。
 
+### Claude Code
+
+在 Claude Code 里逐行执行:
+
 ```bash
-# Claude Code(推荐)— 在 Claude Code 里逐行执行
 /plugin marketplace add https://github.com/Jason-chen-coder/dev-skills
 /plugin install dev-skills
+```
+
+### Codex
+
+当前兼容方式是在 shell 里把 skill 目录复制到 Codex skills 目录:
 
-# Codex(当前兼容方式)— 在 shell 里执行
+```bash
 git clone https://github.com/Jason-chen-coder/dev-skills.git
 cd dev-skills
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 cp -R skills/* "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+Codex 用户如果需要团队级 always-on 规则,当前可先参考 `CLAUDE.md.template` 手动整理到项目根的 `AGENTS.md`;正式的 `AGENTS.md.template` 会在 Codex 兼容迁移中补齐。
 
-# 或 npx skills(跨 agent CLI)
+### npx skills
+
+跨 agent CLI 安装方式:
+
+```bash
 npx skills add Jason-chen-coder/dev-skills              # 项目级
 npx skills add Jason-chen-coder/dev-skills --global     # 全局
+```
+
+### 团队规则模板
 
-# Claude Code 用户:别忘了 CLAUDE.md(手动复制团队约定模板到项目根)
+Claude Code 用户别忘了手动复制团队约定模板到项目根:
+
+```bash
 curl -O https://raw.githubusercontent.com/Jason-chen-coder/dev-skills/main/CLAUDE.md.template
 mv CLAUDE.md.template CLAUDE.md
 ```
 
-Codex 用户如果需要团队级 always-on 规则,当前可先参考 `CLAUDE.md.template` 手动整理到项目根的 `AGENTS.md`;正式的 `AGENTS.md.template` 会在 Codex 兼容迁移中补齐。
-
 <sub>完整安装 / 兜底方案 / 升级路径 → <a href="./docs/onboarding.md">docs/onboarding.md</a></sub>
 
 ---

diff --git a/skills/dev-fix/SKILL.md b/skills/dev-fix/SKILL.md
@@ -61,6 +61,30 @@ baseline 与本 skill 的关联点(本 skill 的核心):
 
 如果以上信息缺关键项(尤其 Repro 起点 / Symptom),**直接向用户追问补全**,不要自己猜。补全前不进 Step 2。
 
+### Clean-tree worktree checkpoint(进入任何文件写入前)
+
+dev-fix 通常会在 Step 2b 写 failing test,之后在 Step 6 写修复。**第一次写文件前**必须检查:
+
+```bash
+git status --short
+git branch --show-current
+```
+
+判定:
+
+- 如果 `git status --short` 为空,且本次 bug fix 会写测试 / 代码 / 配置,先询问用户是否创建独立 worktree。
+- 当前分支是 `main` / `master` / `release/*` 时,默认推荐 worktree。
+- 可跳过询问的场景:用户已明确说当前目录改 / 当前已经在专用 worktree 或任务分支 / 纯单文件 typo。
+- 当前 working tree 已经 dirty 时,不要把本次 fix 混进已有改动;先说明已有改动,由用户决定继续当前目录 / 清理 / 另建基于 HEAD 的 worktree。
+
+推荐命令:
+
+```bash
+git worktree add -b codex/<bug-slug> ../<repo>-<bug-slug>
+```
+
+创建后在新 worktree 内确认 `git status --short` 为空,再写 failing test。
+
 ---
 
 ## Step 2 — Reproduce(失败测试入仓的硬门槛)

diff --git a/skills/dev-plan/SKILL.md b/skills/dev-plan/SKILL.md
@@ -85,6 +85,13 @@ baseline 与本 skill 的关联点:
 2. <步骤> — `path/to/y.ts` 改 Y 行为
 ...
 
+### Workspace setup
+- 实施前运行 `git status --short` 和 `git branch --show-current`。
+- 如果 working tree 干净,且本 plan 会修改代码 / 多文件规则 / 配置 / 测试,先询问用户是否创建 worktree。
+- worktree 默认命名:`git worktree add -b codex/<short-slug> ../<repo>-<short-slug>`。
+- 如果当前分支是 `main` / `master` / `release/*`,默认推荐 worktree。
+- 如果 working tree 已经 dirty,先保护现有改动,不要把本 plan 的改动混进去。
+
 ### Open questions (留给后续)
 - ...
 ```
@@ -257,6 +264,13 @@ ADR 是最终决定的**单一入口**,后续 dev-code-review 评审时如果 di
 1. <步骤> — `path:line`
 2. ...
 
+## Workspace setup
+- Run `git status --short` and `git branch --show-current` before implementation.
+- If the tree is clean and this plan will modify code / multi-file rules / config / tests, ask whether to create a worktree before the first file write.
+- Recommended worktree command: `git worktree add -b codex/<short-slug> ../<repo>-<short-slug>`.
+- If the current branch is `main` / `master` / `release/*`, recommend the worktree path by default.
+- If the tree is already dirty, protect existing changes and do not mix this plan into them without user confirmation.
+
 ## Risks & mitigations
 | Risk | Mitigation |
 |---|---|
@@ -307,6 +321,7 @@ ADR 是最终决定的**单一入口**,后续 dev-code-review 评审时如果 di
 - **不要** 替用户决定 Out of scope 之外的事 —— ADR 里 Follow-ups 段是「应做未做」,不是「我替你决定下一步做什么」。
 - **不要** 写代码 —— 本 skill 只产 plan,代码由后续动作触发。
 - **不要** 自动调起其他 skill —— dev-skills 之间松耦合,plan 完成后用户自己决定下一步。
+- **不要** 省略 Workspace setup —— 任何会进入代码/配置/测试修改的 plan,都必须写明 clean-tree worktree checkpoint。
 
 ---
 

diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
@@ -152,6 +152,35 @@ fixes/<slug>.md 存在 + 其他 status   → Phase X-blocked (见 --recover)
 
 **无法明确推断时**(例如 fixes/<slug>.md 存在但 status 字段缺失),直接告诉用户「我看到 X 但不确定状态,请说一下你刚跑完什么 / 现在卡在哪」。
 
+### Clean-tree worktree checkpoint(仅当下一步会进入写代码)
+
+如果推荐链的下一步或后续步骤包含「写代码 / 修代码」,在输出建议前先检查:
+
+```bash
+git status --short
+git branch --show-current
+```
+
+判定:
+
+| 情况 | 输出要求 |
+|---|---|
+| `git status --short` 为空,且任务是 moderate / complex 或会修改代码 / 多文件规则 / 配置 / 测试 | 在「下一步」后追加 worktree checkpoint,推荐用户先创建独立 worktree |
+| 当前分支是 `main` / `master` / `release/*` | 默认推荐 worktree;若用户坚持当前目录,提醒会直接修改当前目录 |
+| 当前已经 dirty | 不推荐直接创建 worktree;提示已有改动,先让用户决定继续当前目录 / 清理 / 另建基于 HEAD 的 worktree |
+| simple typo / 单文件小文档 / 用户明确说当前目录改 | 可省略 checkpoint |
+
+推荐格式:
+
+```
+编码前检查
+  当前 git tree 干净,且下一步会修改代码/多文件。
+  建议先创建 worktree:
+  $ git worktree add -b codex/<short-slug> ../<repo>-<short-slug>
+```
+
+worktree 命名遵守 `CLAUDE.md.template` 的规范:`codex/<short-slug>` 分支 + 兄弟目录 `<repo>-<short-slug>`。
+
 ---
 
 ## Step 4 — 输出推荐(默认模式)
@@ -177,6 +206,9 @@ Slug   : <feature-slug>(自动推断,你可以纠正)
 下一步
   $ <精确命令,可复制粘贴>
   为什么:<一句话 rationale,不超过两行>
+
+编码前检查
+  <仅当下一步会写代码且 clean tree checkpoint 命中时输出;否则整段省略>
 ```
 
 ### 推荐链对照表