# Agents Writer Design

> AGENTS.md 结构蓝图设计 — 基于项目画像，设计章节规划、门禁布局、行为规则和红线边界，产出可直接用于撰写的内容大纲

- Skill: `morning-start/agents-writer-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morning-start/agents-writer-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morning-start/agents-writer-design/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-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 撰写的直接输入。

```yaml
# 结构蓝图 (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 留合理的自主空间 |