# Agents Writer Gate Check

> 21 项质量门禁验收 — 逐条检查 AGENTS.md 是否符合战略、行为、格式三层质量标准，输出结构化验收报告

- Skill: `morning-start/agents-writer-gate-check` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morning-start/agents-writer-gate-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morning-start/agents-writer-gate-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: morning-start (https://skillmd.com/u/morning-start)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/morning-start/agents-writer-gate-check

---


# ④ 门禁验收

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

## 任务目标

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

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

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

---

## 验收流程

### 检查工具

```bash
# 快速检查 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](../../references/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](../../references/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%+ 的内容使用祈使句（以动词开头）。
- **修复建议**：统一为祈使语气。

---

## 验收报告输出

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

```yaml
# 验收报告 (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）。