Agents Writer

AGENTS.md 战略设计师 v1.0.0

核心哲学

AGENTS.md 是 Agent 的作战手册，不是项目的产品说明书。

这是理解这个技能的基石。很多 AGENTS.md 写成了项目 README 的翻版 — 介绍项目是什么、用什么技术栈、有什么功能。但 Agent 不需要这些。Agent 需要知道的是：

• 在这个项目中，我该怎么做？ — 行为规范
• 我什么能做、什么绝对不能做？ — 边界约束
• 解决问题时要按什么步骤来？ — 工作流
• 做完后如何确保质量？ — 门禁验收

参考 obra/superpowers 的做法：它的 AGENTS.md 不是描述项目，而是定义了从 brainstorming → 写计划 → TDD 开发 → 代码审查 → 完成分支的一整套 Agent 行为模式。每个 skill 都是对 Agent 行为的精确约束。

五维设计框架

产出高质量的 AGENTS.md 需要从五个战略维度审视：

┌─────────────────────────────────────────────────────┐
│                  五维设计框架                          │
├─────────────┬───────────────────────────────────────┤
│  ① 产品定位  │ 这个项目是做什么的？解决什么问题？             │
│  ② 目标用户  │ 使用者是谁？开发者/运维/PM？他们在什么场景使用？ │
│  ③ 功能边界  │ 哪些事 Agent 可以做？哪些绝对不能碰？         │
│  ④ 安全检查  │ 数据权限、操作安全、不可触达的红线               │
│  ⑤ 架构规划  │ 代码怎么组织的？各层之间如何协作？              │
└─────────────┴───────────────────────────────────────┘

关键原则：这五个维度必须从项目文档（README、docs、代码结构）中提取，不应凭空猜测。当文档不足以判断时，必须向用户提问澄清，不能跳过。

前置硬门禁

在进入任何子技能之前，必须通过以下检查。任何一项不通过，暂停流程并向用户提问。

□ GATE-0: 是否已读取项目 README 和 /docs 下的主要文档？
   → 如果没有，先读。文档是设计的依据。
□ GATE-1: 是否已确认用户的项目类型和技术栈？
   → 如果不确定，列出你已知的，向用户确认。
□ GATE-2: 用户期望的 AGENTS.md 风格？（精简/标准/完整）
   → 默认：中等规模项目使用"标准"风格。
□ GATE-3: 是否有现存的 AGENTS.md/CLAUDE.md/.cursorrules？
   → 如果有，先读它，评估后再决定重构还是增量修改。

五阶段工作流

用户请求创建/修改 AGENTS.md
    │
    ▼
┌──────────────────────────────────────────┐
│  GATE-0~3: 前置硬门禁                      │
│  (必须先读文档，不清楚的要问用户)              │
└──────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────┐
│  阶段 1: 分析 (1-analyze)                  │
│  五维分析项目 → 输出项目画像                 │
│  (产品定位 / 目标用户 / 功能边界 /         │
│   安全检查 / 架构规划)                     │
└──────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────┐
│  阶段 2: 设计 (2-design)                   │
│  设计 AGENTS.md 结构蓝图 → 输出大纲         │
│  (章节规划 / 门禁定义 / 行为规则 /         │
│   红线边界 / 工作流设计)                   │
└──────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────┐
│  阶段 3: 撰写 (3-write)                    │
│  按蓝图撰写完整内容 → 输出 AGENTS.md 草稿    │
│  (五维映射为具体指令 / 反模式检测 /         │
│   Token 效率优化)                         │
└──────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────┐
│  阶段 4: 门禁验收 (4-gate-check)           │
│  质量门禁逐条检查 → 输出验收报告             │
│  (21 项门禁 / 安全检查 / 反模式扫描)        │
└──────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────┐
│  阶段 5: 维护 (5-maintain)                 │
│  交付后迭代优化 → 输出更新计划              │
│  (版本管理 / 反馈闭环 / 持续改进)           │
└──────────────────────────────────────────┘
    │
    ▼
    交付最终 AGENTS.md

快捷路径（基于用户需求选择）：

• 快速创建（用户已有清晰想法）：分析 → 设计 → 撰写 → 门禁
• 仅审查（已有 AGENTS.md）：直接进入门禁验收（跳过分析/设计/撰写）
• 仅重构结构（内容好但乱）：设计 → 撰写（复用现有内容）
• 迭代优化（已有 v1）：门禁验收 → 维护（更新版本）
• 从零搭建（新项目）：全流程，分析阶段最重

子技能路由

复合场景路由：

质量门禁总览（21 项）

每个门禁在对应子技能中有详细检查方法。最终验收时 21 项必须全部通过。

战略层门禁（5 项）

行为层门禁（8 项）

格式层门禁（8 项）

参考文件索引

与超级项目（superpowers）的关系

本技能的设计哲学参考了 obra/superpowers 的核心思想：

本质区别：superpowers 是一个通用的开发方法论，而本技能是为特定项目定制其 Agent 行为规范的方法论。

注意事项

⚠️ 不要写成 README：AGENTS.md 回答的是"Agent 在这个项目里该如何工作"，不是"这个项目是什么"。如果写出来的内容可以放在 README 里，那方向就错了。

⚠️ 先读文档再问用户：在麻烦用户之前，先读 README、docs/、package.json、代码结构。大部分信息能从项目本身获取。

⚠️ 不清楚就问：如果读文档后仍然对产品定位、目标用户、安全边界不清晰，不要猜——列出你的假设，向用户确认。猜错的代价远高于问的代价。

⚠️ 门禁不可跳过：除非用户明确说"跳过检查"，否则 21 项门禁必须逐条验证。

⚠️ Token 效率是硬约束：AGENTS.md 是每次对话都加载的，核心内容应 ≤ 500 行。如果超过，考虑拆分为子技能。

版本历史