2 design

② 门禁式结构设计

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

任务目标

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

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

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

风格选择指南：

风格	适用场景	预估行数	复杂度
精简	个人项目、脚本、实验性项目	40-80 行	★☆☆☆☆
标准	小团队项目、中型库	80-200 行	★★★☆☆
完整	大型项目、多 Agent、企业级	200-500 行	★★★★★

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

---

蓝图设计流程

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 要求，满足后才能继续            │
├──────────────────────────────────────────────────┤
│  质量门禁                                          │
│  参考文件索引                                       │
└──────────────────────────────────────────────────┘

门禁类型：

类型	标记	含义	数量建议
硬门禁	<HARD-GATE>	不可跳过，必须通过	1-3 个
软门禁	<GATE>	建议通过，特殊情况可跳过	3-5 个
检查点	[ ]	提醒性质的 check list	5-10 个

Step 3: 行为规则设计

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

规则粒度要求：

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

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

规则来源映射：

五维维度	提取为规则	示例
产品定位	优先级规则	"始终优先实现核心功能，非核心功能只做 MVP"
目标用户	沟通规则	"面向开发者用户，在错误信息中直接给出技术细节"
功能边界	操作规则	"Agent 可以创建 src/.ts 文件，但不能修改 deploy/"
安全检查	红线规则	"永远不要在代码中硬编码 API 密钥，检测到密钥字符时报警"
架构规划	导航规则	"新的 API 端点放在 api/v2/ 目录下，遵循现有的路由约定"

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: [规则列表]

---

常见设计陷阱

陷阱	表现	修复
说明书化	开头写大段项目介绍	把介绍移到 README，AGENTS.md 只写操作指南
过于乐观	只写能做什么，不写不能做什么	必须有一个"红线"章节
规则冲突	两条规则互相矛盾	检查规则的逻辑一致性
缺乏可验证性	"保证高质量" 没有量化标准	改为 "测试覆盖率 ≥ 80%，Lint 零警告"
过度约束	每行代码都要注释，每步都要确认	给 Agent 留合理的自主空间