Project Standards

必读项目规范

> 进入项目后、开始任何工作前，必须执行此 skill。 违反 = 重复劳动、文件冲突、用户偏好被忽略、多AI各自为政。 > > 版本历史见 [CHANGELOG.md](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 "/scripts/check.py" --size   # 各层文档 KB vs 阈值
python "/scripts/check.py" --ci     # 一条命令跑全部闸门（align+size+graph+propagation+loops）

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

---

运行模式（先判这个）

> 解决最大痛点——别让小改动被逼走完整 L1→L5 全链。详见 [layer6-change-tiering.protocol.md](templates/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/.md               ← L1-L5「已闭环历史」溢出于此
        blueprint-adr-.md / polish-history.md …    （append-only 历史真相源·只移不删·活跃层留指针）

---

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

> L1/L2 拆错 = 整个项目走偏。 失败多不在写代码，在一开始就拆错意图。完整话术/对照样例见 > [layer1-intent.protocol.md](templates/layer1-intent.protocol.md) + [layer2-alignment.protocol.md](templates/layer2-alignment.protocol.md) + [examples/intent-good-vs-bad.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 条 / 衍生功能数 项目无 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](templates/layer1-intent.protocol.md) · 模板 [layer1-intent.md](templates/layer1-intent.md)。同时建 intent_log.md（意图变更时间线，初始化记一行）+ 载入 [L7 通用意图](#l7-通用意图价值观铁律)。

L2 alignment.md ⛔ STOP GATE

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

协议 [layer2-alignment.protocol.md](templates/layer2-alignment.protocol.md) · 模板 [layer2-alignment.md](templates/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](templates/layer3-blueprint.protocol.md) · 模板 [layer3-blueprint.md](templates/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](templates/layer4-ai-readme.protocol.md) · 模板 [layer4-ai-readme.md](templates/layer4-ai-readme.md)。 关键规则：目录三件套（path/purpose/examples）齐全；≥3 条 forbiddenpaths；--align violations==0 才许新建文件。AIREADME.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](templates/layer5-plan.protocol.md) · 模板 [layer5-plan.md](templates/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](templates/layer6-meta.md)、瘦身见 [layer6-compaction.protocol.md](templates/layer6-compaction.protocol.md)、变更分级见 [layer6-change-tiering.protocol.md](templates/layer6-change-tiering.protocol.md)、版本治理见 [layer6-version-governance.protocol.md](templates/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](templates/layer6-meta.md) "漂移识别 & 修法" 处理；体量超标按 [layer6-compaction.protocol.md](templates/layer6-compaction.protocol.md) 归档瘦身。自检结果写进 .progress/judgment.json（schema 见 [judgment-contract.md](templates/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](templates/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--{design\|impl-plan}.md | 文件名带日期即版本快照 | | 新研究计划/spec | docs/superpowers/specs/ 或 plans/ | 同上 | | 新 mockup/原型 | docs/mockups/ | — | | 新记忆（单主题） | ~/.claude/projects//memory/{project_\|feedback_\|reference_}.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取代] |

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

• 仓库文档：git log -p / git show : 查任意历史版本；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 "/scripts/standards-gate.py" commit  [--memory]

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

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

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

---

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

> 初始化时载入 INTENT.md「约束」段。7 条任何项目共享，违反 = 工作作废。 自检方法详见 > [layer7-universals.md](templates/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](templates/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](templates/layer1-intent.md) · [layer2-alignment.md](templates/layer2-alignment.md) · [layer3-blueprint.md](templates/layer3-blueprint.md) · [layer4-ai-readme.md](templates/layer4-ai-readme.md) · [layer5-plan.md](templates/layer5-plan.md)

各层执行协议（AI 内化，不写项目）：[layer1](templates/layer1-intent.protocol.md)（五问+反模式）· [layer2](templates/layer2-alignment.protocol.md)（三步拆解+质量自检）· [layer3](templates/layer3-blueprint.protocol.md)（三件事+ADR+风险）· [layer4](templates/layer4-ai-readme.protocol.md)（目录守门+禁止路径）· [layer5](templates/layer5-plan.protocol.md)（Phase 四件套+exit 铁律）

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

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

---

check.py 模式总览

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

| 模式 | 作用 | 退出码 | |------|------|--------| | （无参数） | 层状态 + plan 探测 | 0 | | --align | 文件 ↔ AIREADME 目录规范对齐审计 | 有未登记文件 →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 时间优先）+ dayssincelastrun + 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 "/scripts/check.py" --ci（任一闸门 FAIL 即拦提交）。

---

常见违规与纠正

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gulagala001
• Source: gulagala001/project-standards-skill
• License: MIT

Install and usage instructions live in the source repository linked above.