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、代码结构）中提取，不应凭空猜测。当文档不足以判断时，必须向用户提问澄清，不能跳过。

---

<HARD-GATE> 前置硬门禁

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

□ 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）：门禁验收 → 维护（更新版本）
• 从零搭建（新项目）：全流程，分析阶段最重

---

子技能路由

阶段	子技能	用户说什么时触发	核心产出
① 分析	1-analyze	"分析项目"、"看看这个项目适合什么样的 AGENTS.md"	项目画像（五维评分）
② 设计	2-design	"设计结构"、"规划章节"、"应该包含什么"	AGENTS.md 结构蓝图
③ 撰写	3-write	"帮我写"、"开始写内容"、"撰写"	AGENTS.md 完整草稿
④ 门禁验收	4-gate-check	"检查"、"验收"、"质量门禁"、"评估"	验收报告 + 修复建议
⑤ 维护	5-maintain	"优化"、"迭代"、"更新"、"重构"	更新计划 + 版本管理

复合场景路由：

用户说	执行顺序
"给我这个项目写个 AGENTS.md"	①→②→③→④
"看看我的 AGENTS.md 写得怎么样"	④
"帮我把现有的 AGENTS.md 重构一下"	④→②→③→④
"新启动一个项目，配一下 Agent 环境"	①→②→③→④
"我的 AGENTS.md 太长了，优化一下"	④→⑤→③→④
"像 superpowers 那样给我的项目配 AGENTS.md"	①→②→③→④（完整方法论路线）

---

质量门禁总览（21 项）

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

战略层门禁（5 项）

#	门禁	检查内容	负责子技能
G1	产品定位是否清晰	AGENTS.md 是否体现了项目的核心定位？	④ gate-check
G2	目标用户是否明确	是否区分了谁在读这份文档？	④ gate-check
G3	功能边界是否定义	Agent 能做什么/不能做什么是否明确列出？	④ gate-check
G4	安全检查是否完备	是否有关键的安全红线？	④ gate-check
G5	架构是否被正确反映	代码结构、分层、依赖关系是否被正确体现？	④ gate-check

行为层门禁（8 项）

#	门禁	检查内容
G6	触发条件明确	何时激活此 AGENTS.md？触发词是否具体？
G7	行为规则可执行	每条规则是否足够具体到可执行？
G8	红线清晰	"不能做"的事情是否明确列出？
G9	工作流步骤可操作	每个步骤是否可独立执行？
G10	异常处理有定义	Agent 遇到不懂的事情该怎么办？
G11	优先级有标注	P0/P1/P2 是否合理分配？
G12	责任边界明确	多 Agent 场景下职责是否不重叠？
G13	质量标准有量化	通过/不通过的判断标准是否可衡量？

格式层门禁（8 项）

#	门禁	检查内容
G14	不含反模式	反模式库 中的模式是否全部避免？
G15	不含教程内容	没有"什么是 XXX"的教程式介绍
G16	YAML 前言区完整	name/description/tags 全部存在
G17	Token 效率合理	核心内容 ≤ 500 行
G18	引用路径正确	所有链接指向的文件存在
G19	层级深度合规	目录深度 ≤ 3 层
G20	无重复内容	没有在两个地方说同一件事
G21	语气一致	指令型的祈使语气贯穿全文

---

参考文件索引

文件	内容	什么时候读
references/analysis-framework.md	五维分析框架的完整方法论 + 每个维度的评估指标	阶段 1 分析时
references/gates-templates.md	每个门禁的具体检查方法 + 修复指南	阶段 4 验收时
references/security-checklist.md	安全红线的完整清单 + 每种风险的应对策略	阶段 1 和阶段 4
references/anti-patterns.md	18 种反模式 + 实例对照	阶段 3 撰写和阶段 4 验收

---

与超级项目（superpowers）的关系

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

superpowers 的做法	agents-writer 的映射
AGENTS.md 定义完整的开发方法论	每个项目的 AGENTS.md 都应定义自己的方法论
skill 是行为约束单元	AGENTS.md 的每个章节都是行为约束
先 brainstorming 再动手	先分析再设计再写
严格的 PR 门禁	21 项质量门禁
"你的人类伙伴" 的协作关系	定义 Agent 与人的协作模式
不写代码先写测试（TDD）	不写内容先写门禁（Gate-first）

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

---

注意事项

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

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

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

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

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

---

版本历史

版本	日期	变更
v1.0.0	2026-07-05	🎉 初始版本：五维战略框架 + 5 阶段工作流 + 21 项质量门禁