Agents Writer Design

② 门禁式结构设计

superpowers 的 AGENTS.md 之所以强大，不是因为它的格式好，而是因为它用清晰的章节结构精确地约束了 Agent 在每个阶段的行为。结构设计 = 行为设计。

任务目标

基于阶段 1 输出的项目画像，设计 AGENTS.md 的结构蓝图。蓝图决定最终的 AGENTS.md 是"项目说明书"还是"Agent 作战手册"。

进入前必须完成

□ 阶段 1 的项目画像已存在（五维评分完整）
□ 已与用户确认项目画像的准确性
□ 已确定 AGENTS.md 的风格类型（精简/标准/完整）
□ 已了解用户是否有偏好的结构模板

风格选择指南：

默认选"标准"，除非项目画像明确显示项目极简或极复杂。

蓝图设计流程

Step 1: 核心模块选择

AGENTS.md 由若干核心模块组成。根据项目画像，选择需要包含的模块：

必选模块（所有风格都必须包含）：

□ YAML 前言区     — name / description / tags
□ 身份与角色      — Agent 在项目中的角色定位
□ 核心原则        — 3-5 条不可违背的铁律
□ 行为规则        — 能做什么 / 不能做什么（功能边界映射）
□ 工作流          — 标准问题的解决步骤

可选模块（根据项目类型选择）：

□ 触发条件        — 关键词触发表（纯技术项目不需要，行为驱动型项目需要）
□ 命令速查        — 常用命令参考（有复杂 CLI 的项目需要）
□ 安全检查        — 安全红线清单（涉及数据/生产的项目需要）
□ 多 Agent 协作    — 角色分工（多 Agent 项目需要）
□ 架构速查        — 代码导航指南（大型项目需要）
□ 异常处理        — Agent 遇到不确定情况的处理方式
□ 质量门禁        — 自检清单
□ 参考文件索引     — 链接到详细文档

Step 2: 门禁布局设计

在 AGENTS.md 的关键位置嵌入门禁（Gate）。门禁是强制停顿点，迫使 Agent 在执行关键操作前停下来确认。

门禁布局规则：

┌─ AGENTS.md ───────────────────────────────────────┐
│  <HARD-GATE> 前置门禁（第一条铁律）                  │
│  内容: 不读 README 之前，不要动手                    │
├──────────────────────────────────────────────────┤
│  身份与角色                                        │
│  核心原则                                          │
│  <HARD-GATE> 行为门禁（操作手册的核心）               │
│  内容: 列出绝对不能做的事                            │
├──────────────────────────────────────────────────┤
│  工作流                                            │
│  <GATE> 交付门禁（完成每个步骤前的检查点）              │
│  内容: 完成这一步有 XYZ 要求，满足后才能继续            │
├──────────────────────────────────────────────────┤
│  质量门禁                                          │
│  参考文件索引                                       │
└──────────────────────────────────────────────────┘

门禁类型：

Step 3: 行为规则设计

行为规则是 AGENTS.md 的灵魂。从五维画像提取具体规则。

规则粒度要求：

❌ 太模糊: "注意代码质量"
✅ 可执行: "提交前运行 cargo test，确保所有测试通过"

❌ 太模糊: "不要破坏现有功能"
✅ 可执行: "修改任何现有函数签名前，先搜索所有调用点，确保同步更新"

规则来源映射：

Step 4: 输出结构蓝图

设计完成后，输出结构化的蓝图。这是阶段 3 撰写的直接输入。

# 结构蓝图 (structure-blueprint.yaml)
style: <精简 / 标准 / 完整>
estimated_lines: <预估行数>

modules:
  required:
    - yaml-frontmatter
    - identity-and-role
    - core-principles
    - behavior-rules
    - workflow
  optional:
    - trigger-conditions
    - command-reference
    - security-gates
    - multi-agent
    - architecture-guide

gates:
  hard:
    - position: <在文档中的位置>
      condition: <门禁条件>
      action: <不通过时怎么办>
  soft:
    - position: <位置>
      condition: <条件>

rules:
  priority: [规则列表]
  communication: [规则列表]
  operation: [规则列表]
  security: [规则列表]
  navigation: [规则列表]

常见设计陷阱