# Agents Writer Write

> AGENTS.md 内容撰写 — 将结构蓝图转化为完整的 AGENTS.md，确保五维设计映射为可执行的行为规则和门禁

- Skill: `morning-start/agents-writer-write` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morning-start/agents-writer-write`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morning-start/agents-writer-write/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-write

---


# ③ 策略性内容撰写

> 写 AGENTS.md 不是在写文档，而是在**编程 Agent 的行为**。每一行文字都是对 Agent 行为的一次约束或指引。

## 任务目标

基于阶段 2 的结构蓝图，将五维项目画像转化为可执行的 AGENTS.md 内容。

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

```
□ 结构蓝图已确认（含模块列表和门禁布局）
□ 项目画像已确认（五维评分完整）
□ 已阅读 [anti-patterns.md](../../references/anti-patterns.md) 避免常见错误
```

---

## 撰写流程

### Step 1: 搭建框架

按蓝图中的模块顺序，先写出每个模块的标题和门禁占位符：

```markdown
---
name: <project>-agents
version: v1.0.0
description: <触发条件描述>
tags: [tag1, tag2, tag3]
---

# <Project> Agent 配置

## 核心原则
(3-5 条铁律，标注门禁)

## 行为规则
### 允许的操作
### 禁止的操作
### <HARD-GATE> 红线

## 工作流
### 标准流程
### 快捷路径

## 质量门禁
[ ] 门禁 1
[ ] 门禁 2
```

### Step 2: 逐模块填充

每个模块的填充方法：

#### YAML 前言区

```yaml
---
name: my-project-agents           # {project-name}-agents
version: v1.0.0                   # 语义化版本
description: >
  ## 触发条件                    ⚠️ 这是最重要的部分！
  当用户提及以下内容时立即激活：
  - "关键词A / 关键词B / 关键词C"  
  - "场景描述1 / 场景描述2"
  注意描述要"pushy"一点，包含足够的触发场景。
tags: [tag1, tag2, tag3]          # 3-6 个标签
---
```

**描述写作指南**：
- 使用 "when user mentions X, Y, Z" 句式
- 包含具体的关键词和场景
- 略微 pushy — 宁可误触发也不要遗漏
- 不超过 150 字（50-100 最佳）
- 参考 [obra/superpowers](https://github.com/obra/superpowers) 的做法：描述要具体到让 Agent 能够准确判断是否应该使用

#### 身份与角色

告诉 Agent 它在项目中扮演什么角色、具备什么能力。参考 superpowers 的 CLAUDE.md：

```markdown
## 身份与角色

你是 <项目名> 的 <角色>。你的核心职责是：
- <职责 1>
- <职责 2>

在这个项目中，你需要特别关注：
- <关注点 1>
- <关注点 2>
```

#### 核心原则

3-5 条不可违背的铁律。每条都要解释"为什么重要"（让模型理解原因，而非机械服从）：

```markdown
## 核心原则

### R1: 先理解再动手
在你写任何代码之前，先花时间理解需求。大多数 bug 来自理解偏差。
**为什么重要**：这个项目有复杂的领域逻辑，提前花 2 分钟理解需求可以避免 2 小时的重写。

### R2: 不破不立 — 但有底线
可以重构代码，但绝不能破坏现有 API 兼容性。
**为什么重要**：项目的 API 被多个外部团队依赖，即使小的签名变更也需要同步更新。

### <HARD-GATE> R3: 不碰红线
永远不要修改 deploy/ 目录下的文件。永远不要提交 .env 文件。
**为什么重要**：这些文件直接关联生产环境安全，手动修改需要三层审批。
```

#### 行为规则

这是 AGENTS.md 的核心。从五维画像提取：

```markdown
## 行为规则

### ✅ 允许的操作
| 操作 | 条件 | 示例 |
|------|------|------|
| 创建源代码文件 | 在 src/ 目录下 | `src/features/*.ts` |
| 运行测试 | 任何时间 | `npm test` |
| 修改配置文件 | 仅限开发环境 | `.env.development` |

### ❌ 禁止的操作
| 操作 | 原因 | 替代方案 |
|------|------|---------|
| 修改生产配置 | 直接影响线上服务 | 提交 PR 走审批流程 |
| 直接推送 main 分支 | 绕过代码审查 | 创建 feature 分支 + PR |
| 删除数据库迁移文件 | 破坏数据一致性 | 创建新的迁移文件 |

### <HARD-GATE> 🚫 红线（不可触达）
这些操作即使看起来"没问题"，也绝对不要执行：
1. 永远不要执行 `rm -rf` 相关的命令
2. 永远不要在生产数据库上运行 DDL
3. 永远不要将 API 密钥硬编码到代码中
4. 永远不要修改 .github/workflows/ 下的文件
```

#### 工作流

定义 Agent 解决问题的标准步骤：

```markdown
## 工作流

### 标准流程：实现新功能
1. **理解需求** — 阅读相关文档，确认理解
2. **搜索现有代码** — 查找类似实现，复用模式
3. **编写测试** — 先写测试再写实现代码
4. **实现** — 最小化实现，满足测试即可
5. **审查** — 对照门禁自检
6. **提交** — 创建 PR

### 快捷流程
- **修 bug**：复现 → 定位根因 → 写测试 → 修复 → 验证
- **加文档**：找对应模块 → 更新 API 文档 → 检查示例代码
- **代码审查**：功能完整性 → 安全性 → 性能 → 代码风格
```

### Step 3: Token 效率优化

AGENTS.md 在每次对话中都会加载，必须控制体积。

**Token 优化清单**：
```
□ 移除了所有"项目介绍"类内容（这些在 README 里）
□ 用表格替代长段落
□ 门禁使用了 <HARD-GATE> 标记而非重复描述
□ 参考文件用链接指向而非内联
□ 命令示例使用了代码块而非逐行说明
□ "为什么重要" 控制在 1-2 句话
□ 没有重复的规则（同一件事只在一个地方说）
```

**估算 Token 的方法**：
```bash
# 粗略估算：行数 × 3 ≈ Token 数
wc -l AGENTS.md
echo "Token 估算: $(($(wc -l < AGENTS.md) * 3))"
# 更准确：直接用 wc -c 估算（中文字符每个约 1.5 token）
# 精确估算需要 tokenizer
```

### Step 4: 自检五维映射

确保 AGENTS.md 的内容完整覆盖了五维画像的所有关键发现：

| 五维 | 在 AGENTS.md 中的映射检查 |
|------|--------------------------|
| 产品定位 → | 核心原则中是否体现了产品优先级？ |
| 目标用户 → | 沟通风格和错误信息是否匹配用户画像？ |
| 功能边界 → | 行为规则是否完整列出了"允许"和"禁止"？ |
| 安全检查 → | 是否有红线章节？敏感操作是否有门禁？ |
| 架构规划 → | 工作流中是否包含了代码导航指引？ |

---

## 反模式速查

撰写过程中，对照 [anti-patterns.md](../../references/anti-patterns.md) 逐条检查。

**最常见的 3 个反模式**（撰写时要特别注意）：

1. **教程化倾向** — 花 200 字介绍项目背景
   - ✅ 正确：直接定义 Agent 的行为规则
   - ❌ 错误：写"XX 项目是一个开源项目，由 YY 团队维护..."

2. **过度乐观** — 只写能做什么
   - ✅ 正确：明确列出"禁止的操作"
   - ❌ 错误：只有"你可以做 A、B、C"

3. **规则模糊** — "注意代码质量" 这种不可量化的话
   - ✅ 正确："测试覆盖率 ≥ 80%，通过所有 lint 检查"
   - ❌ 错误："保持代码整洁"