4 gate check

④ 门禁验收

superpowers 拒绝 94% 的 PR，因为它的门禁严格到近乎苛刻。AGENTS.md 的质量门禁也应该如此 — 宁可多花 5 分钟检查，也不要交付一个有缺陷的 Agent 配置。

任务目标

对已完成的 AGENTS.md 逐条执行 21 项质量门禁检查，输出结构化的验收报告，标明每项门禁的通过状态、证据和不通过时的修复建议。

<HARD-GATE> 进入前必须完成

□ AGENTS.md 草稿已完成
□ 项目画像已存在（作为对照基准）
□ [anti-patterns.md](../../references/anti-patterns.md) 已准备好用于扫描

---

验收流程

检查工具

# 快速检查 AGENTS.md 结构
cat AGENTS.md

# 检查 YAML 前言区
head -20 AGENTS.md

# 检查行数
wc -l AGENTS.md

# 检查教程化词汇
grep -ciE "(^## .*简介|^### .*介绍|什么是|what is|background|overview)" AGENTS.md

# 检查禁止操作章节
grep -c "禁止" AGENTS.md
grep -c "红线" AGENTS.md

# 检查门禁标记
grep -c "<HARD-GATE>" AGENTS.md
grep -c "<GATE>" AGENTS.md

---

21 项门禁逐条检查

战略层（5 项）

G1: 产品定位清晰

• 检查方法：通读 AGENTS.md，是否能找出项目的核心定位？如果看完了还不知道项目是做什么的，就不合格。
• 通过标准：核心原则中至少有一条与产品定位直接相关。
• 检查命令：grep -A5 "^## 核心原则" AGENTS.md
• 修复建议：在核心原则中添加一条与产品定位相关的工作优先级规则。

G2: 目标用户明确

• 检查方法：文档的语气和粒度是否匹配目标用户水平？技术细节的深度是否合适？
• 通过标准：整个文档的语气一致，没有同时出现"新手友好"和"专家向"的内容。
• 修复建议：识别用户的水平后，统一调整文档的术语深度。

G3: 功能边界定义

• 检查方法：是否同时有"允许的操作"和"禁止的操作"两章？
• 通过标准：明确的 3-5 条"禁止"，且有具体的文件和目录路径。
• 检查命令：grep -cE "(禁止|不允许|不能|不要|never|don't)" AGENTS.md — 结果应 ≥ 3
• 修复建议：如果没有禁止章节，必须补充。参考项目画像中的功能边界。

G4: 安全检查完备

• 检查方法：是否有安全相关的规则？红线章节是否覆盖了项目画像中的安全检查发现？
• 通过标准：如果项目涉及用户数据或生产环境，必须有专门的安全章节。
• 修复建议：参考 security-checklist.md 补充安全规则。

G5: 架构正确反映

• 检查方法：工作流中的路径和目录名是否与实际项目结构一致？
• 通过标准：工作流中提到的路径在实际项目存在。
• 检查命令：提取 AGENTS.md 中的所有路径，用 ls 验证是否存在。
• 修复建议：修正不存在的路径引用。

---

行为层（8 项）

G6: 触发条件明确

• 检查方法：AGENTS.md 的 description 字段是否有具体的触发词？是否明确说明"什么时候用"？
• 通过标准：包含 3 个以上的具体触发场景或关键词。
• 修复建议：补充触发场景，参考 main SKILL.md 的 description 写法。

G7: 行为规则可执行

• 检查方法：随机选 3 条规则，是否能明确判断"这条规则被执行了还是没被执行"？
• 通过标准：所有规则都有可观察的判断标准。
• 修复建议：模糊的规则改为"做 X 之前先做 Y"的可操作指令。

G8: 红线清晰

• 检查方法：是否有用 <HARD-GATE> 标记的不可触达红线？
• 通过标准：至少 1 个 <HARD-GATE> 标记的红线，且明确说明了"为什么不能做"。
• 检查命令：grep -c "<HARD-GATE>" AGENTS.md — 结果应 ≥ 1
• 修复建议：至少定义 1 条不可触达的红线。

G9: 工作流步骤可操作

• 检查方法：每步是否以动词开头？是否有明确的输入输出？
• 通过标准：每步都可以独立执行，不依赖前一步的隐含信息。
• 修复建议：将模糊步骤拆分为可独立执行的小步骤。

G10: 异常处理有定义

• 检查方法：AGENTS.md 是否告诉 Agent "遇到不确定的事情怎么办"？
• 通过标准：明确写了"当 XX 时不明确时，向用户提问"或类似策略。
• 修复建议：添加"不确定时暂停并提问"的规则。

G11: 优先级标注

• 检查方法：核心任务是否标记了 P0/P1/P2 优先级？
• 通过标准：至少 P0 和 P1 级别的任务有优先级标记。
• 修复建议：按功能模块的重要性分配优先级。

G12: 责任边界明确

• 检查方法：如果是多 Agent 场景，每个 Agent 的职责是否不重叠？
• 通过标准：没有两条规则指向同一个操作但给出不同指示。
• 修复建议：合并冲突规则，明确职责归属。

G13: 质量标准可量化

• 检查方法："足够好"的标准是否有具体的数字或条件？
• 通过标准：至少有一条质量规则是可量化的（如"覆盖率 ≥ 80%"、"零 warning"）。
• 修复建议：为质量要求添加量化阈值。

---

格式层（8 项）

G14: 不含反模式

• 检查方法：逐条对照 anti-patterns.md 扫描。
• 通过标准：零反模式命中。
• 修复建议：按反模式中的修复方案逐条修正。

G15: 不含教程内容

• 检查方法：grep -ciE "(简介|介绍|什么是|what is|background|overview)" AGENTS.md
• 通过标准：教程类关键词出现 ≤ 1 次（且不在合理语境中）。
• 修复建议：将教程内容移到 README。

G16: YAML 前言区完整

• 检查方法：检查文件开头的 YAML。
• 通过标准：name、version、description、tags 四个字段都存在。
• 检查命令：head -15 AGENTS.md | grep -E "^(name|version|description|tags):"
• 修复建议：补充缺失的前言区字段。

G17: Token 效率合理

• 检查方法：wc -l AGENTS.md
• 通过标准：核心内容 ≤ 500 行。超过时考虑拆分为子技能。
• 检查命令：wc -l < AGENTS.md
• 修复建议：将 > 500 行的内容拆分，主文件保留路由+门禁，详细内容移到子文件。

G18: 引用路径正确

• 检查方法：提取所有 ]( 路径，检查文件是否存在。
• 通过标准：所有引用路径指向的文件都存在。
• 检查命令：grep -oP '\]\([^)]+' AGENTS.md | sed 's/\]\(//' | while read p; do ls $p 2>/dev/null || echo "MISSING: $p"; done
• 修复建议：修正不存在的路径。

G19: 层级深度合规

• 检查方法：目录嵌套深度是否超过 3 层？
• 通过标准：AGENTS.md 不引用深度 > 3 层的文件（从项目根开始算）。
• 修复建议：展平深层目录结构。

G20: 无重复内容

• 检查方法：搜索相同的指令是否出现在两个不同的章节。
• 通过标准：没有内容相同的两个段落。
• 检查命令：grep -c "同一个核心指令" AGENTS.md — 结果应 ≤ 1
• 修复建议：合并重复内容，保留一份权威来源。

G21: 语气一致

• 检查方法：通读全文，检查是否混合使用了"请"、"必须"、"可以"、"建议"等不一致的语气。
• 通过标准：90%+ 的内容使用祈使句（以动词开头）。
• 修复建议：统一为祈使语气。

---

验收报告输出

检查完成后，输出格式化的验收报告：

# 验收报告 (gate-report.yaml)
summary:
  total_gates: 21
  passed: <通过的数目>
  failed: <未通过的数目>
  pass_rate: <通过率百分比>
  
strategic_layer:
  - gate: G1-产品定位
    status: ✅ 通过 / ❌ 未通过
    evidence: <检查证据>
    fix: <不通过时的修复建议>
  - gate: G2-目标用户
    ...
    
behavior_layer:
  - gate: G6-触发条件
    ...

format_layer:
  - gate: G14-不含反模式
    ...

recommendations:
  critical: <必须修复的问题列表>
  suggested: <建议改进的问题列表>
  optional: <可选改进的问题列表>

---

与用户的交互

验收完成后，向用户呈现：

1. 通过/未通过统计：21 项中通过了多少
2. 关键失败项：必须修复的问题（标红色）
3. 建议改进项：推荐但不是必须的改进
4. 下一步建议：是直接交付还是修复后再验收

征得用户同意后，进入阶段 5 维护，或在修复后重新验收（重复阶段 4）。