Project standards skill

必读项目规范

进入项目后、开始任何工作前，必须执行此 skill。 违反 = 重复劳动、文件冲突、用户偏好被忽略、多AI各自为政。

版本历史见 CHANGELOG.md。本文件是索引 + STOP GATE + 模式选择——展开细节在 templates/*.protocol.md，需要时按指针去读。

---

核心原则

不做检查 = 不可开工      不读文档 = 不知道上下文      不写文档 = 下一个人还会重蹈覆辙

---

启动流程

进入项目后按顺序执行：

Step	动作
0 定位根	找含 .git/ 或 CLAUDE.md 或 AI_README.md 的目录 = $PROJECT_ROOT
1 读规范	按优先级读：AI_README.md（总纲/目录规范）→ CLAUDE.md（项目级配置）→ MEMORY.md（用户偏好/历史）→ STRATEGIST.md（策略方向）。先找到先读，没有跳过
2 判初始化	无 AI_README.md = 未初始化 → 走 初始化流程
3 查 plan	ls docs/plan*.md docs/plans/*.md PLAN.md TASK_PLAN.md，已有就读它，不要新建
3.5 体量自检	见下方 ⚠️，跑 --size，有 [!!] OVER 先归档再开工
4 定运行模式	见 运行模式：冷启动 or 热迭代？热迭代再判改动级别

Step 3.5 体量自检（L6 Loop 5）

⚠️ 用本 skill 自带的 check.py（路径 = 加载本 skill 时给出的 Base directory/scripts/check.py）。 不要用项目里的 scripts/check.py 副本——它可能是早于体量层的旧拷贝（缺 --size/--ci 等模式会报错）。 check.py 是本 skill 的单一真相源，跟项目无关，绝不依赖项目内副本是否同步。

python "<本-skill-base-dir>/scripts/check.py" --size   # 各层文档 KB vs 阈值
python "<本-skill-base-dir>/scripts/check.py" --ci     # 一条命令跑全部闸门（align+size+graph+propagation+loops）

--ci 是给 git hook / CI 的单一入口，任一闸门 FAIL 即退出码 1。各模式详见 check.py 模式总览。

---

运行模式（先判这个）

解决最大痛点——别让小改动被逼走完整 L1→L5 全链。详见 layer6-change-tiering.protocol.md。

模式	触发	怎么走
冷启动（初始化）	项目无 AI_README.md	走下方 初始化流程，建齐 L1-L5
热迭代（维护）	已初始化	按改动级别对号入座，不必每次全链

热迭代三级（边界从严就高）：

级别	判据	要求
trivial 快车道	单文件 bug 修 / 文案 / ≤~50 行，不新增 FEAT、不改接口、不改意图	只改代码 + 变更日志追一行（触发链段=无）。不触发传播链、不强制 STOP GATE。⚠️但碰共享引擎/安全/删除/接口签名/数据格式 → 升级到 standard
standard	一个 FEAT 范围内的功能	走受影响相邻层（通常 L3 feat_plan + L5 Phase），传播只穿透相邻层
structural	改意图 / 新顶层 INT / 换技术选型 / 删功能 / 大重构	走完整 L1→L5 传播链 + STOP GATE + ADR

trivial 豁免传播链，但不豁免留痕（变更日志一行）和最终 Loop 自检。

---

分层规范体系

L1 用户意图 + 时间线   INTENT.md + intent_log.md        ← 一切从这里出发
L2 意图-项目对齐       alignment.md                     ← 意图→子目标→功能
L3 实现总纲           blueprint.md                     ← 功能→技术方案
L4 AI_README.md      （入口文件）                       ← 架构 + 目录规范唯一真相源
L5 规范化 Plan        plan.md                          ← 与 L3/L4 对齐
L6 元规则（skill 内）                                    ← loop 机制 + 改动传播 + 体量瘦身 + 变更分级
L7 通用意图（skill 内）                                  ← 项目初始化自动载入的价值观铁律
─────────────────────────────────────────────
归档层  docs/archive/ + memory/<topic>.md               ← L1-L5「已闭环历史」溢出于此
        blueprint-adr-<范围>.md / polish-history.md …    （append-only 历史真相源·只移不删·活跃层留指针）

---

意图拆解方法论（L1/L2 必读）

L1/L2 拆错 = 整个项目走偏。 失败多不在写代码，在一开始就拆错意图。完整话术/对照样例见 layer1-intent.protocol.md + layer2-alignment.protocol.md + examples/intent-good-vs-bad.md。

四个最常翻的坑：① 把用户的"动作"当"成果"（"做个看板"≠"每周5分钟看清偏没偏"）② 没追"为什么"就拆功能 ③ 没边界，顺手把 B/C/D 也做了 ④ 降级偷换（要 100% 年化做成 10% 稳，违反 L7#7）。

L1 · 挖意图五问（写 INTENT.md 前必须问用户，没说就问、说了反向确认）

#	问题	挖什么
Q1	谁在用？什么场景？	真实使用者 + 触发场景
Q2	不做会怎样？现在怎么凑合？	必要性 + 当前痛点
Q3	三个月后成功长什么样？给画面	具象、可证伪
Q4	什么是"做得不错"但不算你要的？	暴露伪成功路径
Q5	只能选一个，哪个最重要？	强制排序、拒绝"全都要"

五问答案合成"主要目标/成功标准/约束/边界"——不是抄原话。

L1 · 反模式（写完逐项自检）

伪意图（带技术栈）/ XY 问题 / 降级目标 / 拼盘需求（目标>3条都说重要）/ 不可证伪（"能正常运行"）/ 开放边界（"以后看情况"）——命中任一 → 回五问重挖。详见 protocol。

L2 · 三步拆解

1. 复制不发明：INTENT.md 主要目标 一对一 → INT-1/2/3，禁在 L2 发明新顶层意图。
2. 每 INT 必答两问：为什么需要它（追到 L1/价值观）+ 怎么算达到了（可外部观察证伪），答不出就删。
3. 子节点配可观测功能：每个 INT-X.Y 至少挂 1 个 FEAT-X.Y.Z（动词+宾语），没挂=空中楼阁。

粒度硬规则：深度 ≤3 层 / 每层 P0 ≤50% / 顶层意图 ≤3 条 / 衍生功能数 < 主功能数。详见 protocol。

---

初始化流程（冷启动）

项目无 AI_README.md 时执行，按 L1→L5 顺序建齐。每层都有 STOP GATE，任一不过禁止建该层文件。

每层通用操作步骤

1. 打开该层的 templates/layerN-*.protocol.md，先走完协议（五问/拆解/三件套等）。
2. 把产出填进 templates/layerN-*.md 模板，写到 $PROJECT_ROOT/<对应文件>。
3. 填好模板末尾"协议执行记录"表（证明 STOP GATE 真发生了——--gate 会校验勾选）。

L1 INTENT.md ⛔ STOP GATE

1. ☑ 已主动问用户五问 Q1–Q5 并收到实际答复（非 AI 推断、非复读原话）
2. ☑ 已过反模式自检 6 项
3. ☑ 没有任何目标是 AI 凭直觉代答

协议 layer1-intent.protocol.md · 模板 layer1-intent.md。同时建 intent_log.md（意图变更时间线，初始化记一行）+ 载入 L7 通用意图。

L2 alignment.md ⛔ STOP GATE

1. ☑ INTENT.md 已存在且"协议执行记录"全勾
2. ☑ 已读完 INTENT.md（不只扫一眼）
3. ☑ 明白本层不发明意图，只拆 L1 已有意图

协议 layer2-alignment.protocol.md · 模板 layer2-alignment.md。 关键规则：意图无孤儿 / 功能可追溯 / 每层 P0 ≤50% / 深度 ≤3 层。

L3 blueprint.md ⛔ STOP GATE

1. ☑ INTENT.md + alignment.md 都在且两份"协议执行记录"已勾
2. ☑ alignment.md 的 FEAT 树已稳定
3. ☑ 清楚 L3 只画方案不发明功能

协议 layer3-blueprint.protocol.md · 模板 layer3-blueprint.md。 关键规则：每 FEAT 给 接口+数据流+错误路径；≥1 条 ADR、≥1 条 RISK（哪怕都 low）。

L4 AI_README.md ⛔ STOP GATE

1. ☑ blueprint.md 已存在且"协议执行记录"已勾
2. ☑ 已遍历所有顶层文件/夹（排除 .git//__pycache__//node_modules//.venv//dist//build//.collab/{sessions,messages,locks,log}/）
3. ☑ 清楚 AI_README.md 是"目录规范唯一真相源"

协议 layer4-ai-readme.protocol.md · 模板 layer4-ai-readme.md。 关键规则：目录三件套（path/purpose/examples）齐全；≥3 条 forbidden_paths；--align violations==0 才许新建文件。AI_README.md 是每个 AI 进项目读的第一个文件。

L5 plan.md ⛔ STOP GATE

1. ☑ L1-L4 四份都已存在
2. ☑ 已读完 blueprint.md 全部 feat_plans + ADR
3. ☑ 已读完 AI_README.md 目录规范——plan 里所有路径必须符合 L4

协议 layer5-plan.protocol.md · 模板 layer5-plan.md。 关键规则：每 Phase ≥2 条可外部观察的 exit_criteria；Phase 依赖无环、同刻 doing ≤1；偏离一条记一条（plan.deviations[]，藏=违规）。可解析格式：每个 Phase 用 - **FEAT**: FEAT-X.Y.Z 单独成行，--graph 才能建引用图谱。

---

L6 元规则

L6 不写进项目——是 skill 自己的元规则。完整版见 layer6-meta.md、瘦身见 layer6-compaction.protocol.md、变更分级见 layer6-change-tiering.protocol.md、版本治理见 layer6-version-governance.protocol.md。

改动传播 4 段链

任何 standard/structural 改动必须穿透 L1 ↕ L2 ↕ L3 ↕ L4 ↕ L5，链不许断。每段状态 ok / lag（上游变下游没跟，≤3 天容忍）/ broken（冲突，停下对账）。--propagation 用 mtime 自动测 lag。

• 自上而下（意图变）：改 INTENT.md → 追 intent_log.md → 看 L2 是否需新 FEAT → 是则一路 L2→L3→L4→L5；否则只更新受影响下游并标来源。
• 自下而上（方案撞墙）：先在 L5 内修 → 修不动标 plan.deviations 向上 → 触及 L3 改方案/ADR superseded → 触及 L2 拆/删 FEAT → 触及 L1 停下等用户确认。只动这条路径上的层；每跳一层记一行变更日志（含「触发链段」）。

Loop 6 类自检（完成 Phase / 每周 / 进项目时跑）

#	名称	检查	失败形态	自动化
1	回路闭合	INT 都能追到 doing/done 的 Phase	僵尸意图	--graph
2	上游可追溯	plan/blueprint 节点都能追到 alignment	野生功能	--graph
3	下游已落地	done 的 FEAT 有代码/测试/文档证据	假完成	人工抽样
4	新鲜度合规	5 份核心文档在窗口内更新过	文档腐烂	--loops
5	体量合规	各层在体量阈值内	文档臃肿	--size
6	版本治理合规	当权文档有最后更新:行、记忆有updated:字段、无 v2 并存文件、被推翻结论有去向标注	载入读到旧结论/历史丢失	人工抽样

失败按 layer6-meta.md "漂移识别 & 修法" 处理；体量超标按 layer6-compaction.protocol.md 归档瘦身。自检结果写进 .progress/judgment.json（schema 见 judgment-contract.md），供 /进度 skill 渲染。

AI 行为约束（协作 8 条 · 初始化时载入 INTENT.md「约束」段）

1. 工作必须留痕（写入文档/代码/commit，不止存在于对话）
2. 代码与文档同步（改代码同步改 AI_README/CLAUDE.md/plan）
3. 协作先读文档（进项目先读 L1-L5，避免重复劳动）
4. 基于数据决策（测试/日志/监控，不凭直觉）
5. 多 AI 必须协作（共享上下文、互读文件、统一入口）
6. 只向用户汇报 L1+L2（L3 以下自行决策，不询问不汇报）
7. 优先实现用户意图（不用降级/保底/临时妥协替代原目标）
8. 版本治理（载入只读最新当权内容；改结论留旧版本去向；仓库文档靠 git+最后更新:行、记忆靠覆盖不删除+updated:字段；不建 v2 并存文件——详见《文件创建与版本治理规范》）

---

文件创建与版本治理规范（L6 横切子段 · 适用全层）

目标：AI 每次载入（新对话）只读最新当权内容，不被旧结论带偏；要查历史时能查到有时序记录。AI 自主路由，不问用户"这放哪"。执行协议见 layer6-version-governance.protocol.md，机器闸门 check.py --version-governance。

禁止

不检查就创建（已有同类还新建）/ 文件乱丢（不符 AI_README 目录规范）/ 重复建 plan / 跨 AI 各自建文档不互读 / 为同一主题建 v2/v3 并存文件（仓库文档靠 git、记忆靠文件内时间线，禁返祖式版本文件）/ 原地改结论不留痕（改当权结论必须留旧版本去向）。

正确流程（建任何新文件前）

① 查 AI_README.md 目录规范 → ② 查目标路径是否已有同类 → ③ 有则读后追加/更新不新建 → ④ 无则按目录规范建。

新内容路由（该新建还是并入——AI 自主判定）

内容类型	落点	规则
新 feature/设计稿	docs/specs/YYYY-MM-DD-<slug>-{design|impl-plan}.md	文件名带日期即版本快照
新研究计划/spec	docs/superpowers/specs/ 或 plans/	同上
新 mockup/原型	docs/mockups/	—
新记忆（单主题）	~/.claude/projects/<proj>/memory/{project_|feedback_|reference_}<slug>.md	一主题一文件，不建 v2 文件；原文件内更新
仓库根文档改动	原地改（CLAUDE.md/plan.md/blueprint.md/INTENT.md/alignment.md/AI_README.md）	git 即版本记录
记忆更新	原文件内，旧结论降级历史段	见下「记忆覆盖不删除」

退役/归档路由（旧版本该去哪——AI 自主判定）

情形	动作
spec/plan 被取代	移 docs/archive/，原位置删；记忆索引同步
结论性文档被推翻（review/audit 类）	移 docs/archive/ + 顶部加 ⚠️<日期>快照，已被<XX>覆盖
当权文档结论被推翻但文件仍当权	不删不移，原地改 + 顶部加 最后更新: 行 + 旧结论降级历史段标日期
记忆结论被推翻	不删文件，文件内旧结论标日期降级，新结论置顶（覆盖不删除）
记忆整条作废	文件改墓碑（保留避悬空链接）+ 索引行标 [已删除/被XX取代]

时序记录（查历史——AI 自主查得到）

• 仓库文档：git log -p <file> / git show <hash>:<file> 查任意历史版本；docs/archive/ 看退役快照；specs 文件名日期即版本。
• 记忆库：单文件内时间线（旧结论标日期降级，新结论置顶）；要查某主题演进读那一个文件。
• 载入默认只读最新：新对话注入 CLAUDE.md + MEMORY.md 索引；记忆文件按相关性召回只读最新段；文档顶部 最后更新: 行判断是否当权。

记忆覆盖不删除（写记忆时强制）

改记忆结论时：旧结论不删，降级为历史段并标日期（如「→2026-06-21 已反转」），新结论置顶。frontmatter 强制 updated: YYYY-MM-DD 字段，每次改 bump。这样单文件自带时间线，不丢演进，也不爆炸式增文件。

当权文档顶部行（写/改仓库文档时强制）

CLAUDE.md/plan.md/blueprint.md/INTENT.md/alignment.md/AI_README.md 及 docs/ 下当权文档，顶部必须有 最后更新: YYYY-MM-DD · 状态: 当权|快照 行。快照类（archive/、被推翻的 review）标 快照，当前权威标 当权。让 AI 一眼判断该不该信。

改当权内容走 standards commit（读写守门）

PM 裁决（2026-06-22）：改当权文档 / 记忆结论必须走 standards-gate.py commit 守门——单次校验 + 自动 commit + git 留底；草稿区（docs/specs/、docs/mockups/、docs/archive/）和错别字直改自由，不走守门。

改当权文档或记忆结论，改完调：

python "<本-skill-base-dir>/scripts/standards-gate.py" commit <file> [--memory]

• 校验（过则继续，不过打回）：
  • 当权文档：最后更新: 行已 bump 到本次改动日；无 v2 并存文件；不含「已被取代/已废弃」标记。旧结论去向不机器检查——仓库文档靠 git log 留底（body 多日期是正常现象，启发式会误判）。
  • 记忆（--memory）：updated: 字段已 bump；旧结论已降级历史段标日期；无 v2 并存文件。
• 通过后：仓库文档 → 自动 git add <file> && git commit（commit message 带守门标记）；记忆 → 校验通过即放行（记忆靠文件内时间线，不进 git）。
• 不通过：打回，报告哪条没过 + 改法，不自动 commit。
• 查历史：standards-gate.py history <file> 看该文件守门提交记录（仓库文档走 git log；记忆无独立历史）。

这把版本治理从「只读机器扫 + 人工语义复核」升级到「读写守门」：check.py --version-governance 扫形式层违规（只读），standards-gate.py commit 在改结论时强制 bump / 去向 / 无并存后才放行并留 git 底（读写）。详见 layer6-version-governance.protocol.md《读写守门 standards-gate.py commit》段。

前向适用（过渡条款）：本段两条强制规则（updated: 字段、最后更新: 顶部行）对新写/改写的文件立即生效；存量文件下次触碰时补齐，不要求一次性全项目改造。check.py --version-governance 对缺失项只 warn 不阻塞（v2 并存才 error），避免一上线即全红。

---

L7 通用意图（价值观铁律）

初始化时载入 INTENT.md「约束」段。7 条任何项目共享，违反 = 工作作废。 自检方法详见 layer7-universals.md。/进度 的 L7 板渲染这 7 条，两 skill 严格对齐。

1. 服务真实用户 — 工作能 1 句话连到 INTENT.md 某条意图，不是"看起来有用"
2. 可证伪 over 可解释 — 验收可外部观察证伪，拒"做好/完善/稳定/可用"
3. 可验证 over 可声称 — 每条"已完成"有可指向证据（commit/test/文件/截图）。--evidence 给它装了执行体：done 旁写 commit:/file:#sym/test: proof-token，机器逐条 resolve，证据撒谎即 exit 1；--proof-drift 守护它不随时间烂掉
4. 简单 over 完备 — 当前最小可工作版本优先，"为以后"的代码/抽象砍掉
5. 当下问题优先 — 先解决用户今天就痛的，"以后可能重要"不算计划
6. 痛感诚实 — 卡顿/不确定/走不通立刻暴露，禁"正在处理/即将完成/应该可以"遮羞
7. 小步可逆 — 每 Phase ≤1 周、每步可独立 git revert，禁大爆炸式重写

自检数据格式：.progress/judgment.json 的 universals.checks[] 恰好 7 条（id 1-7），每条 passed/severity/evidence。schema 见 judgment-contract.md。

---

项目文件结构模板

$PROJECT_ROOT/
  AI_README.md   INTENT.md   intent_log.md   alignment.md   blueprint.md   plan.md
  CLAUDE.md   MEMORY.md   STRATEGIST.md          ← 如有
  docs/  (archive/ 历史归档)   data/   results/   src/（或项目特定结构）
  .collab/                                       ← 多 AI 协作系统（可选/legacy，见下）

初始化时按项目实际调整目录，写入 AI_README.md。

---

跨 AI 使用方法

• Claude Code：/project-standards 或对话开头说"先执行 project-standards skill"。
• GPT / Codex / 其他：读取并执行本 SKILL.md（核心逻辑不依赖 CC 特定功能），可作 system prompt / 知识库加载。

多 AI 协作（默认：worktree + 文件分区）

首选做法——多 AI 并行时按文件分区：每个 AI 认领互不重叠的文件集，必要时各自用独立 git worktree 隔离，由统揽者集成。无需任何协作框架，零冲突，已是实战默认。

可选 / legacy：若项目已有 .collab/ 系统，它与本 skill 互补——.collab/protocol.md 管"怎么协作"（锁/消息/任务），本 skill 管"怎么规范项目"。.collab 非必需；新项目不必引入。

---

模板与协议文件

各层填写模板（输出到项目根）：layer1-intent.md · layer2-alignment.md · layer3-blueprint.md · layer4-ai-readme.md · layer5-plan.md

各层执行协议（AI 内化，不写项目）：layer1（五问+反模式）· layer2（三步拆解+质量自检）· layer3（三件事+ADR+风险）· layer4（目录守门+禁止路径）· layer5（Phase 四件套+exit 铁律）

L6 元规则：layer6-meta.md（传播链+Loop 6 自检）· layer6-compaction.protocol.md（体量瘦身+归档层）· layer6-change-tiering.protocol.md（冷/热双模式+变更分级）· layer6-semantic-audit.protocol.md（Loop 3 语义四态审计）· layer6-version-governance.protocol.md（Loop 6 版本治理·载入只读最新+覆盖不删除+不建v2并存）

L7 + 契约 + 版本：layer7-universals.md（7 铁律+自检）· judgment-contract.md（judgment.json 共享 schema）· CHANGELOG.md（版本历史）

---

check.py 模式总览

本 skill 自带 scripts/check.py（stdlib only）。用 skill 自带的，别用项目内副本（见 Step 3.5 警告）。

模式	作用	退出码
（无参数）	层状态 + plan 探测	0
--align	文件 ↔ AI_README 目录规范对齐审计	有未登记文件 →1
--size	L6 Loop 5 体量合规（文档臃肿）	有超标 →1
--graph	L6 Loop 1/2 引用图谱（僵尸意图 / 野生功能）	有孤儿 →1
--gate [layer]	STOP GATE 协议执行记录勾选校验	有未勾选 →1
--propagation	传播链相邻层 lag 体检（git 提交时间优先，回退 mtime）	有 lag →1
--loops	Loop 4 新鲜度（git 时间优先）+ days_since_last_run + AI_README↔src 落后	有 stale →1
--ci	聚合闸门（git hook / CI 单一入口；含 align+size+graph+propagation+loops，不含 evidence/gate/proof-drift）	任一 FAIL →1
--evidence（别名 --gate-done）	L7#3 取证：done 行 proof-token（commit:/file:#sym/test:）逐条 resolve	证据撒谎才 →1
--proof-drift	证据断链哨兵：复查历史 done 证据现在还成不成立	file/test 断链 →1（commit 软 warn）
--scaffold	反向脚手架：报代码已存在但文档零提及的模块 + DRAFT 初稿（只读不写）	0（助手非闸门）
--fix	漂移修复工单：各模式失败 → 改哪/怎么验（只读不改）	有工单 →1

pre-commit 一行：python "<skill-base>/scripts/check.py" --ci（任一闸门 FAIL 即拦提交）。

---

常见违规与纠正

违规	后果	正确做法
不读 AI_README 就开工	文件放错位置	先读入口文件
不检查已有 plan	重复计划	先 ls / --graph
改代码不改文档	文档腐烂	同步更新
方案行不通闷头硬试	浪费时间	向上追溯，必要时问用户
两 AI 各自写 plan	冲突混乱	先检查，有就沿用；文件分区
小改动也走全套 L1-L5	累到干脆跳过 skill	按运行模式判级，trivial 走快车道
文档只增不减 → 读不全	上下文丢失、静默腐烂	--size 把关，闭环历史归档留指针