小型团队 AI Coding 实战手册

Anthropic Steering 文讲的是「指令往哪放」；MCP 是工具连接层，不是同一种东西。团队规范的第一件事不是「写更长的 CLAUDE.md」，而是把每条指令放到正确的机制里——放错地方，轻则浪费 token，重则关键规则被淹没。

另有 output styles / --append-system-prompt（改角色或单次附加系统提示），小团队少用。别把 MCP 当成「第八条 CLAUDE.md」——它解决的是能调什么外部系统，不解决「项目规则写在哪」。

判据一句话：删掉这行，agent 会做错什么？答不上来就删。必须永远做对 → 别只写 markdown，写成 hook 或测试。

小团队最常见的失败是一上来装 100 个 skill、抄 500 行 CLAUDE.md。按 Anthropic 内部与一线仓库收敛出的顺序：先能验证 → 再共享宪法 → 再自动化 → 再谈高级流程。

1. Day 1 · 每个活跃仓库能「自证」 确认本地有：测试命令、lint/format、CI 对 PR 的同一套命令。没有测试的模块，先给 agent 一个可跑的 check（哪怕是脚本 diff fixture）。官方第一原则：Give Claude a way to verify its work。
2. Day 1–2 · 薄宪法 + docs Day-0 跑 /init，删到 <150–200 行。共享事实写 AGENTS.md，Claude 用薄 CLAUDE.md @AGENTS.md。每人 CLAUDE.local.md + gitignore。应用仓按 §8 项目目录 搭 Day-0 树并填 docs/context/project-context.md——没填就别让 agent 大写代码。
3. Day 2 · 装三条强制门禁 ① PreToolUse 拦写 .env / secrets 与危险 rm；② PostToolUse 对改动文件 format/lint；③ git pre-commit 密钥扫描。慢检查（全量 Sonar/CodeQL）放 CI，不要塞进每次 Edit。
4. Day 3 · 工作流纪律写进宪法，不写成长篇小说 三句话够用：非琐碎改动先 plan；完成前必须跑验证命令；同问题纠正两次就 /clear 重开。大流程用 skill，不塞 CLAUDE.md。
5. Day 4–5 · 选一个流程 skill，不是二十个 从「发版检查」或「PR 自检」二选一。有副作用的加 disable-model-invocation: true。流程型 skill 同阶段只留一个主将（见 Agentic · skill 治理）。
6. Day 5 · 定人 + 定 PR 规则 指定 Constitution Owner（可兼职）。约定：改 AGENTS.md / hooks / 共享 skill 走 PR；agent 大 diff 不免除人类 review；禁止用 --no-verify 当日常文化。

Week-0 完成定义：任意成员在干净 clone 上能：用同一套命令绿测、agent 读到同一份宪法、危险写操作被 hook 拦住、PR 上 CI 与本地 check 一致。应用仓额外：project-context 里验证命令非占位符，且有一份带验收标准的 active requirement。

官方 best practices 开篇几乎不是 CLAUDE.md，而是验证。没有 pass/fail 信号，你就是验证环本身——每个错误都等你发现。团队 AI 规范的 ROI，首先体现在agent 能否自己跑到绿。

实战坑：把 10 分钟分析塞进 agent hook → 全员关掉 hook → 底线归零。慢检查上 CI；快检查贴 agent 手边。

第一性原理：CLAUDE.md 不是「另一个 README」，而是每次会话自动注入的行为说明书。写错位置的成本是：同事被你的个人习惯绑架，或你的续跑断点被提交进库。Linux/WSL 文件名必须是 CLAUDE.md（大小写敏感）。官方建议单文件 <200 行；无主的 monorepo 宪法会只增不减——要有 owner，改动走 PR。

层级地图

内容分级速查（统一 vs 放开）

关键区分：全局是你个人的，项目是团队共享的。项目级会被所有人的 Claude 读到——必须是客观事实，不能放个人习惯。进度与续跑写进项目 CLAUDE.md，是多人协作第一号脏数据来源。

项目级 CLAUDE.md：团队共享的必选板块

跨工具时：客观事实优先写 AGENTS.md，Claude 用薄 CLAUDE.md 做 @AGENTS.md + 少量 Claude 专用路由。改团队宪法 = 提 PR，至少一人 review，避免把个人习惯写进去。

CLAUDE.local.md：私人笔记本（推荐，别塞进 ~/.claude/projects 就忘）

官方支持 ./CLAUDE.local.md（或 ./.claude/CLAUDE.local.md）：启动时加载，同层追加在 CLAUDE.md 之后。默认应 gitignore。相对 ~/.claude/projects/<encoded-path>/：local 文件就在仓库根，肉眼可见，更不容易忘——适合「快速进入状态 / 续跑 / 本仓事实源」。

• Worktree：gitignore 后 local 不会随 worktree 自动出现。多 worktree 时：每棵拷一份，或在 local 里 @~/notes/<项目>.md 指到家目录一份个人文件。
• settings.local.json：本机 hook/权限微调放这里；行为说明放 local.md。安全门禁（拦 rm、拦 .env）必须进共享 hooks，不能只写在 local。
• 团队纪律：PR 扫到误提交的 CLAUDE.local.md 一律打回；根 .gitignore 固定包含它。

# CLAUDE.local.md — 本机私有，勿提交
# .gitignore 必须包含：CLAUDE.local.md

## 快速进入状态
- 当前工程：<名称>（openspec change `<id>`）
- 续跑：/openspec-apply <id>
- 断点：openspec/changes/<id>/tasks.md

## 事实源（个人档案）
- 设计文档：<Obsidian 路径>
- 项目大脑：Obsidian 40-Projects/<项目>/index.md

## 本机
- API：http://localhost:18080
- DB：docker compose --profile dev up -d

## 禁止
- 密码 / token / 客户数据
- 应写进团队 CLAUDE.md / AGENTS.md 的规则

模板全文见 §11。会话用 /memory 确认 local 已加载。

全局个人层：补全本机环境，方法论只写一次

• 思维方式、开工路由、验证纪律、记忆/档案总约定：写在 ~/.claude/CLAUDE.md，不要复制进每个仓库的团队 CLAUDE.md。
• 本机环境写全（减少每次「试探」）：node 绝对路径、包管理器（如 uv）、gh 账号与协议、WSL/内网入口等——仍是你的机器，不是团队事实。
• 若某条约定已变成「全员必须」（如「统一用 uv」）→ 升格进项目 AGENTS.md，而不是只留在你的全局文件。

薄与可验证（官方留存测试）

加载与冲突

• 从 cwd 向上拼接；同层 CLAUDE.local.md 追加在 CLAUDE.md 后。
• 子目录 CLAUDE.md 启动通常不加载，读到该处文件时才纳入。
• 冲突规则可能被任意遵循一条 → /memory 审计，删冲突。
• 插件根 CLAUDE.md 不是标准插件组件，启用不会自动当 memory。

两套记忆：CLAUDE.md vs Auto Memory

CLAUDE.md 是你写的指令；Auto Memory 是 Claude 自己学的。两套系统互补，但在团队场景下容易混淆——尤其不要把 auto memory 当团队共识。

维护节奏：agent 第二次犯同一错 → 改对应层（团队事实 / 个人 local / 或 hook）。每月修剪；砍不掉的长文挪 skill。留存测试：「去掉这行会不会做错？」

官方推荐默认四步：Explore → Plan → Implement → Commit。Superpowers 把「未批准设计不写码」做成硬门；Compound Engineering 要求每次交付让下次更容易。小团队不需要全套仪式，但需要同一条路由。

会话卫生（官方 failure patterns 压缩）

• 无关任务之间 /clear——厨房水槽会话是第一大坑。
• 同一问题纠正超过两次：停，clear，把教训写进更好的首条 prompt，不要在脏上下文里缠斗。
• 调研用 subagent——避免主会话读几百个文件后失忆。
• 实现与审查分离——writer 与 reviewer 不同上下文（双会话或 subagent）。
• 频繁小 commit——存档点；checkpoint 只跟踪 Claude 改动，不能替代 git。

Hooks 是「模型说了不算」的层。配置进 .claude/settings.json（团队共享）或 managed policy（企业强制）。用 /hooks 核对来源。

Hook 五种类型（不止 shell 命令）

常用生命周期事件：PreToolUse（工具调用前）、PostToolUse（工具调用后）、Stop（结束前）、SessionStart（会话开始）、PreCompact / PostCompact（上下文压缩前后）。完整列表见官方 hooks 文档。

最小可生产五道闸

1. PreToolUse · 安全墙 拦：写 .env / **/secrets/**；破坏性 rm -rf；未授权 force-push。exit 2 + 原因回灌模型。Tech lead 指南普遍把这一条列为「10 分钟最小安全」。
2. PostToolUse · 编辑后整形 matcher Edit|Write：只对变更路径跑 formatter / 快速 lint。官方示例就是 eslint-after-edit。保持独立、有 timeout。
3. Stop · 可选完成门 对关键仓库：结束前跑 npm test --related 或项目脚本；失败则阻止「我做完了」。注意连续 block 上限（官方约 8 次后可被覆盖）——门要准，别无脑全仓。
4. git pre-commit · 进库门 secret 扫描（sk-ant-、AKIA、私钥头等）+ staged 文件检查。与 Claude hook 互补：有人不用 Claude 时仍挡住。
5. CI · 合并门 与本地同一入口脚本（make check / pnpm verify）。Sonar/Semgrep 作 quality gate 或 security job，不绑定交互循环。

配置示例见 §11 模板。原则：hook 失败信息必须可读，否则模型会瞎重试。

Skill = 可复用程序。启动只加载 name/description；装太多时 description 本身就是上下文税。官方：流程放 skill；副作用流程 disable-model-invocation: true。

模型偏差怎么收

• 目标不是字节级相同输出，而是同一验收标准。
• 清单外置（检查项 + 报告格式）> 散文要求「认真点」。
• 实现与验收分离（fresh context）。
• 维护 3–5 个 golden 任务：小 bug / 中 feature / 危险重构；换默认模型或改 skill 前跑一遍。
• 默认便宜模型；失败两次带轨迹升级——别全程 Opus 烧钱掩饰坏 skill。

Agents vs Skills：什么时候用哪个

Skill 是「可复用流程」；Agent（.claude/agents/*.md）是「可复用角色」。Skill 定义步骤；Agent 定义身份、工具权限、模型选择。两者可组合：Agent 预加载 Skill。

判据：需要独立上下文、不同工具权限、或对抗性角色 → Agent。需要步骤化流程、在主会话内执行 → Skill。两者可叠：Agent 定义角色，skills: 字段给它装流程。

AI coding 不是只配 CLAUDE.md。仓库目录本身就是控制系统：控制面（agent 怎么干活）、真相面（产品/技术必须成立什么）、代码面（可运行实现）。下面是一套中小应用仓默认规范——借鉴 AGE 等实践的吸引子思路，但用自己的分层命名，不要求照搬任何模板目录名。

1 · 三面模型（先分区，再放文件）

三面不能互相顶替：hooks 拦不住错误需求；docs 不能当测试；代码里的注释不能当团队 AGENTS.md。

2 · 推荐目录全景（必须 / 推荐 / 按需）

repo/
├── README.md                 # 给人：如何跑起来（可薄）
├── AGENTS.md                 # 给 agent：操作契约【必须·git】
├── CLAUDE.md                 # 薄包装：@AGENTS.md + Claude 专用【必须·git】
├── CLAUDE.local.md           # 个人续跑/本机【必须 gitignore】
├── .gitignore                # 含 CLAUDE.local.md、.env、settings.local
│
├── .claude/                  # 控制面【必须有框架】
│   ├── settings.json         # 共享 hooks / 权限【git】
│   ├── settings.local.json   # 本机微调【gitignore】
│   ├── skills/               # 可调用流程 skill
│   ├── agents/               # 子代理角色定义
│   └── hooks/                # hook 脚本
│
├── docs/                     # 真相面 + 过程记忆
│   ├── index.md              # 文档路由（人/agent 入口）
│   ├── context/              # 【Day-0 必须】当前指针与规则
│   │   ├── project-context.md
│   │   ├── source-of-truth.md
│   │   ├── autonomy.md       # AI 可自主到什么程度
│   │   └── codebase-map.md   # 改哪里、脆点在哪
│   ├── requirements/         # 【必须有 active 一份】可实施需求
│   ├── design/               # 【推荐】稳定的产品/功能行为
│   ├── architecture/         # 【推荐】稳定的技术边界与基线
│   ├── plans/                # 【触发才建】切片执行与关闭条件
│   ├── backlog/              # 【推荐】下一步候选
│   ├── input/                # 【按需】原始 PRD/截图/纪要
│   ├── discussions/          # 【按需】需求澄清
│   ├── logs/                 # 【按需】实施日记（常带日期）
│   ├── bugs/                 # 【按需】非显然回归与根因
│   ├── testing/              # 【按需】手工测记 + known-good
│   ├── lessons/              # 【按需】可复用教训
│   └── archive/              # 【按需】人工批准后的冷文档
│
├── openspec/ 或等价 change 目录  # 【可选】若团队用 OpenSpec：必须在 context 里声明 active
├── src/ 或 apps/ + packages/     # 代码面【必须】
├── tests/                          # 【强烈推荐】
└── .github/workflows/              # CI【推荐】

名字可本地化（例如 docs/context/project-context.md 叫 当前状态.md），但职责不能丢：指针文件、验收需求、稳定设计/架构、过程计划、代码与测试。

3 · 每层写什么（职责表）

4 · 事实源优先级（冲突时用）

冲突处理：需求 vs 设计不一致 → 先改文档再写码；代码 vs 文档不一致 → 标明是实现漂移还是文档过期，禁止静默二选一。文档 freshness 为 stale/unknown 时，默认只调研/对齐，不改产品行为（除非人明确批准）。

5 · 落地方法论（怎么做，不是怎么抄）

1. Day-0 · 搭骨架，只填指针 建控制面三件套（AGENTS / 薄 CLAUDE / local+gitignore）+ .claude/settings.json 空 hooks 也可先就位。真相面只建 docs/index.md + docs/context/* + 一份 active requirement。验证命令写真实命令；占位符则停止实现。
2. 切片开工 · 固定阅读序 Agent/人：project-context → autonomy →（冲突时）source-of-truth → active requirement → owner design/architecture → 相关代码。禁止从聊天长摘要直接开写。
3. 分级施工 · 目录跟级别长 L0：可只改代码 + 相关测，context 指针可不动。
   L1：更新/新建 plan（或 openspec change），任务可勾选，验证门写清；合入前回写 design/requirements 中受影响句。
   L2：先 architecture/design 批准，再拆多 plan；跨模块边界变更必须改 architecture。
4. 关单 · 四问 ① 验收是否用真实命令跑绿？② owner doc 是否回写？③ context 的 active 指针是否更新或清空？④ 非显然坑是否进 bugs/lessons？四问不过不算完成。
5. 演进 · 按触发开目录 第一次需要澄清歧义 → 建 discussions；第一次非显然 bug → 建 bugs；第三次同类失败 → 升 lessons 或 skill。禁止「先开 15 个空文件夹」当规范落地。
6. 治理 · 一人一源 任意时刻：一份 active requirement、至多一份 active plan/change。OpenSpec 与 docs/plans 二选一为主，或在 project-context 写死映射路径——禁止双真相。

6 · 单条变更（Spec）在目录里长什么样

7 · Day-0 最小可复制树

repo/
├── AGENTS.md
├── CLAUDE.md              # @AGENTS.md
├── CLAUDE.local.md        # gitignore
├── .gitignore
├── .claude/
│   ├── settings.json
│   └── hooks/
├── docs/
│   ├── index.md
│   ├── context/
│   │   ├── project-context.md   # active 指针 + 验证命令表
│   │   ├── source-of-truth.md
│   │   ├── autonomy.md
│   │   └── codebase-map.md
│   ├── requirements/mvp-or-slice.md
│   ├── design/app-overview.md
│   └── architecture/system-baseline.md
├── src/
└── tests/

# docs/context/project-context.md（骨架）
## 身份
- 项目：
- 当前里程碑：
- 文档新鲜度：fresh | partially-stale | stale | unknown

## 当前指针（任意时刻只填真实路径）
- Active requirement: docs/requirements/…
- Active owner doc: docs/design/… 或 docs/architecture/…
- Active plan: docs/plans/… 或 openspec/changes/… 或 none
- AI autonomy: implement | plan-first | ask-first | research-only

## 验证命令（禁止占位符）
| 用途 | 命令 |
| 安装 | |
| 开发 | |
| 测试 | |
| Lint | |
| 构建 | |

8 · 反模式（目录专场）

• 文档剧场：空目录 + 空 README 当「已规范化」。
• 真相写进 CLAUDE.md：长需求/进度塞进每次会话，既胀上下文又无版本语义。
• 双 active：两个「当前需求」或 OpenSpec 与 plans 各说各话。
• 散文压过 schema：用 markdown 描述表结构却不改 migration。
• 过程当吸引子：只写日志不改 design，半年后无人知道「系统现在该怎样」。
• 控制面缺失：docs 很全，但无 hooks/CI，底线仍靠自觉。
• 规范演进笔记塞进 CLAUDE.md：对照 AGE 的过程与账本不进会话常驻文件——见下节。

9 · 规范持续演进：Skill + 账本（不污染 CLAUDE.md）

项目与规范都会变。外部模板（如 AGE）适合当只读对照源，不适合拷进每个会话。推荐固定三件套：

1. 触发：改共享规范 / Day-0 后复盘 / 同类翻车第二次 / 季度扫「暂缓」列——日常写码不跑。
2. 对照：按范围只读 AGE 2～5 个文件，输出「采纳 / 暂缓 / 不用」三栏。
3. 决策：用户勾选后更新账本；批准后再改结果文件。
4. 禁令：不把 AGE 长文或演进过程写进任何 CLAUDE.md；不一次 cp -r 全套空目录。

下一批高价值暂缓项（账本已记）：自主等级+保护区、codebase-map、known-good baseline、Plan 决策表/Anti-Slacking——进真实业务仓时优先落地，而不是再抄 AGE 全文。

验收这套目录是否落地：新人（或新会话 agent）只读 project-context + active requirement 就能开工；验证命令可复制跑绿；任意冲突能在 source-of-truth 找到主源；关单后 design/architecture 与代码一致。规范演进可重复跑 skill+账本，且 CLAUDE.md 保持干净。参考实现可对照内部 age-app-template，以本节职责为准裁剪。

共识不是「全员同一模型」，而是全员撞同一堵墙、读同一份说明书、按同一路由升级仪式。Wix 工程侧也在强调：agent 能读 repo，仍缺 PM 意图与半年前决策——那要进 AGENTS.md / Skills / 结构化上下文，不是靠更大模型。

进 git / 不进 git

CLAUDE.md 协作三规则

• 团队 CLAUDE.md / AGENTS.md 是代码的一部分 → 改它 = 提 PR，至少一人 review；只放客观事实，不放个人偏好。
• CLAUDE.local.md 是个人的 → 自己改、不 review；不放团队必须知道的信息；必须在 gitignore。
• 全局 ~/.claude/CLAUDE.md 是个人 OS → 方法论写一次；已变成全员约定的条目，升格到项目共享文件。

PR 最低条

• 人话说明意图与风险；贴验证命令与结果（或 CI 链接）。
• L1+ 链到 change/spec id（id 写在 PR/local，不写进团队 CLAUDE.md）。
• agent 生成不免除 review；可用 agent 分诊，人类拍板合并。
• 改宪法/hooks 与改业务代码分开 PR，方便回滚；误提交 local 文件直接打回。

度量与持续改进（可选，Week-4+ 再加）

没有度量就没有改进。但别一上来就搞仪表盘——先跑一个月，再用数据说话。

度量是改进输入，不是考核指标。发现 hook 绕过率高 → 查 hook 是否太慢；发现自闭环率低 → 查验证命令是否缺失。别把指标当 KPI 压人。

• 厨房水槽会话 · 多任务混一个 context → /clear 或分会话。
• 过厚宪法 · 规则越多，关键规则越容易丢 → 剪枝或改 hook。
• 禁止事项只写 markdown · 压力下会破 → permissions/hook。
• 信任间隙 · 看起来对但没跑验证 → 不绿不合并。
• 无限调研 · 无范围 investigate 吃光窗口 → subagent + 收窄问题。
• Skill 集市成瘾 · 100 个 description 税 + 流程互殴 → 一阶段一主将。
• 慢 hook 文化 · 超时后全员 --no-verify → 快慢分离。
• Spec / docs 坟场 · 只增不 archive；或 20 个空目录文档剧场 → 最小路径 + 废弃标记。
• 双真相 · OpenSpec change 与 docs/plans 各写一套且不互相引用 → 在 project-context 指定唯一 active plan。
• 每人私有神级 prompt · 协作比没 AI 更乱 → 共享内核 + 个人 local。
• 把 auto memory 当团队 wiki · 机器本地、不进 git → 共享事实进 AGENTS/docs。
• 规范演进塞 CLAUDE.md · AGE 对照笔记胀上下文 → skill + 账本 + 结果文件（§8·9）。

自产中文，按需删改。保持薄。规范演进对照 skill 见本机 standards-age-review（不在此粘全文）。

1 · 团队 CLAUDE.md（薄包装 + 客观事实）

# <项目名>

@AGENTS.md

## Claude 专用（可选，仍须是团队共识）
- 非琐碎改动先 plan；完成前贴验证证据
- 同问题纠正两次：/clear 后重来

## 硬禁止（说明；强制靠 hooks/CI）
- 密钥与生产凭据不进库
- 不 force-push 共享分支

# 禁止写入本文件：个人进度、change id、Obsidian 路径、本机端口
# → 放 CLAUDE.local.md（gitignore）

2 · AGENTS.md / 项目共享事实骨架

# AGENTS.md — 团队共享，改它 = 提 PR

## 这是什么
一段话：给谁用、解决什么、当前状态一句。

## 仓库结构
- `src/` …
- `tests/` …
（只列容易迷路的）

## 技术栈与版本
- 语言/框架/关键依赖约束

## 构建与测试
- 安装：
- 开发：
- 测试：（优先相关测）
- Lint / typecheck：
- 构建：
- 部署：或见 ops/README.md

## 代码规范
- 框架特有坑（必写）
- 通用风格：以 linter / editorconfig 为准

## 分支与提交
- 分支策略、commit 格式、PR 要求

## 架构红线
- 不可违反的设计决策

## 常见陷阱
- known gotchas

## 验证 / 完成定义
相关测试与 lint 必须绿。CI：`.github/workflows/…`

## 安全
禁止提交：.env、密钥、客户导出。

3 · 项目 hooks 最小集（settings 片段）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-secrets-path.sh"
        }]
      },
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "if": "Bash(rm *)",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-changed.sh",
          "timeout": 60
        }]
      }
    ]
  }
}

脚本需团队自备：路径黑名单、rm 策略、只格式化变更文件。失败时向 stdout/stderr 写清原因。

4 · CLAUDE.local.md + .gitignore（私人笔记本）

# CLAUDE.local.md — 个人工作流，勿提交 git

## 快速进入状态
- 当前工程：<名称>（openspec change `<id>`）
- 续跑：/openspec-apply <id>
- 断点：openspec/changes/<id>/tasks.md

## 事实源
- 设计文档：<Obsidian 路径>
- 项目大脑：Obsidian 40-Projects/<项目>/index.md

## 本机
- API：http://localhost:18080
- DB：docker compose --profile dev up -d

## 禁止
- 密码 / token
- 团队应共享的规则（写进 AGENTS.md / CLAUDE.md）

# .gitignore（片段）
CLAUDE.local.md
.claude/settings.local.json
.env
.env.*

同层：先团队 CLAUDE.md，后 local。比 ~/.claude/projects/… 更不容易忘。详见 §4。

5 · 副作用 skill frontmatter

---
name: ship-check
description: 发版前检查。仅当用户明确要求发版或 ship 时使用。
disable-model-invocation: true
---

# 发版检查
1. 跑项目 verify 命令，保存摘要
2. 核对 CHANGELOG 与用户可见变更
3. 列出风险与回滚
失败即停：不打 tag、不推送。

6 · L1 PR 自检

## PR checklist
- [ ] 意图与非目标一句话
- [ ] 验证命令 + 结果（或 CI）
- [ ] 无密钥 / 无本机绝对路径
- [ ] L1+ 已链 spec/change
- [ ] 宪法/hooks 变更已拆 PR（如有）
- [ ] 需要时已做 fresh-context review

7 · 规范演进账本行（Obsidian，只追加）

| 日期 | AGE 来源 | 能力点 | 决策 | 落点 | 备注 |
|------|----------|--------|------|------|------|
| YYYY-MM-DD | 文件名 | 一句话能力 | 采纳/暂缓/拒绝/已有等价 | 路径或「—」 | 触发条件或原因 |

# 决策后：改业务仓 AGENTS/docs/hooks，不要改 CLAUDE.md 记过程
# 手动对照：/standards-age-review

8 · 子代理定义（.claude/agents/reviewer.md）

---
name: code-reviewer
description: 审查代码变更的质量、安全与风格。仅在用户要求 review 时使用。
tools: Read, Glob, Grep
model: sonnet
maxTurns: 30
---

你是代码审查员。审查标准：
1. 正确性：逻辑是否完备，边界是否处理
2. 安全：是否有密钥泄漏、注入风险、权限过大
3. 风格：是否符合项目约定（以 AGENTS.md 为准）
4. 测试：变更是否有对应测试覆盖

输出格式：按文件列出发现，每个发现含「问题 → 建议 → 严重度（P0/P1/P2）」。
无发现则输出「LGTM」。

9 · MCP 配置（.mcp.json）

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "local-db": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost:5432/dev}"
      }
    }
  }
}

${VAR} 和 ${VAR:-default} 语法支持环境变量展开。.mcp.json 进 git；密钥通过环境变量注入，不写进文件。用 /mcp 查看连接状态。

10 · 路径限定规则（.claude/rules/api-rules.md）

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

## API 层约定
- 所有入参必须 Zod schema 校验
- 错误统一用 AppError 类，不抛裸 Error
- 响应格式：{ data, error, meta }
- 日志用 logger 工具，不直接 console.log

带 paths: frontmatter 的 rules 只在 Claude 处理匹配文件时加载。适合 monorepo 按模块分规则，避免无关规则污染上下文。

11 · Golden Fixture 回归脚本

#!/bin/bash
# .claude/hooks/golden-fixture.sh
# 在 3-5 个代表性任务上跑 skill 回归
# 用法：./golden-fixture.sh [skill-name]

SKILL=${1:-"code-review"}
FIXTURES=(
  "fixtures/small-bugfix.diff"
  "fixtures/medium-feature.diff"
  "fixtures/risky-refactor.diff"
)

for f in "${FIXTURES[@]}"; do
  echo "=== Testing $SKILL on $f ==="
  claude -p "/$SKILL" < "$f" --output-format json > "results/$(basename $f .diff)-result.json"
done

echo "=== Summary ==="
# 对照预期输出，计算通过率
# 通过率下降 = skill 退化或模型变更，需调查

Golden fixture 是对抗「模型升级后 skill 行为漂移」的结构解。发 skill 改动或换默认模型前跑一遍，记录通过率趋势。

本页刻意少引营销帖。下列是可核对的一手或高引用实践源。

• Anthropic · Claude Code Best Practices 验证闭环、plan 四步、CLAUDE.md 写什么、会话卫生、对抗审查、失败模式——团队规范的主轴。 code.claude.com/docs/en/best-practices核对于 2026-07
• Anthropic · Steering Claude Code（Segner, 2026-06） 七种机制对照表；明确「永远做 Y → hook」「绝对禁止 → hook/permissions」「流程 → skill」。 claude.com/blog/steering-claude-code…2026-06-18
• Anthropic · Memory / Hooks / Skills 文档 四层路径、拼接加载、子目录按需、disable-model-invocation、hook 生命周期。 docs/memory · hooks · skills核对于 2026-07
• AGENTS.md 开放标准 跨 Codex/Cursor/Jules 等的 agent 说明书；与 README 人机分工；60k+ 仓库采用量级。 agents.md核对于 2026-07
• obra/superpowers 可安装的工程级技能链：brainstorm → plan → TDD → 执行 → 验证；硬门方法论的代表实现。 github.com/obra/superpowers持续维护
• Every Inc · Compound Engineering Plugin 「每次工程工作应使后续更容易」；skills 把教训结构化回写。 github.com/EveryInc/compound-engineering-plugin持续维护
• Addy Osmani · AI coding workflow / agentic review CLAUDE.md 与 skills 实践、fresh-context review、agent 做 PR 分诊、loop engineering。 ai-coding-workflow · agentic-code-review2026
• Karpathy 行为约束（forrestchang 打包） 先想/简单/手术刀/目标可测。Augment 实验：质量未必升，效率常升——当控制层校准用。 forrestchang/andrej-karpathy-skills · Augment 评测2026
• Anthropic · Subagents 文档 .claude/agents/*.md 定义格式：name/description/tools/model/permissionMode/isolation/skills。独立上下文，只回摘要。 docs/sub-agents核对于 2026-07
• Anthropic · MCP 文档 .mcp.json 配置格式；http/stdio/ws 传输；环境变量展开；工具按需加载。 docs/mcp核对于 2026-07
• Povilas Korop · 验证墙 约定是样本概率；失败的测试才是墙——别只往 CLAUDE.md 堆规则。 x.com/PovilasKorop2026-07-06
• AGE App Template（只读对照源） 吸引子 + context + SoT + autonomy + plan 关单等厚实现；落地时裁剪进业务仓 docs，不拷空目录、不写进 CLAUDE.md。 本地：alpha-ai-agent/…/age-app-template · START-HERE-after-copy.md核对于 2026-07
• 规范演进：standards-age-review + AGE 账本 手动 skill 对照 AGE 出三栏建议；Obsidian 账本记采纳/暂缓/拒绝；结果落 AGENTS/docs，过程不进 CLAUDE.md。 ~/.claude/skills/standards-age-review · vault 20-Tech/AI-HARNESS/notes/age-adoption-ledger.md2026-07-13
• 站内姊妹篇 Agentic 作战手册（个人选型）· Harness · 循环工程 · 未知项 zbisure.github.io2026-07

偏实战判断。全对才通过。