3 write

③ 策略性内容撰写

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

任务目标

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

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

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

---

撰写流程

Step 1: 搭建框架

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

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

# <Project> Agent 配置

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

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

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

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

Step 2: 逐模块填充

每个模块的填充方法：

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 的做法：描述要具体到让 Agent 能够准确判断是否应该使用

身份与角色

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

## 身份与角色

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

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

核心原则

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

## 核心原则

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

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

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

行为规则

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

## 行为规则

### ✅ 允许的操作
| 操作 | 条件 | 示例 |
|------|------|------|
| 创建源代码文件 | 在 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 解决问题的标准步骤：

## 工作流

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

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

Step 3: Token 效率优化

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

Token 优化清单：

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

估算 Token 的方法：

# 粗略估算：行数 × 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 逐条检查。

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

1. 教程化倾向 — 花 200 字介绍项目背景

   • ✅ 正确：直接定义 Agent 的行为规则
   • ❌ 错误：写"XX 项目是一个开源项目，由 YY 团队维护..."

2. 过度乐观 — 只写能做什么

   • ✅ 正确：明确列出"禁止的操作"
   • ❌ 错误：只有"你可以做 A、B、C"

3. 规则模糊 — "注意代码质量" 这种不可量化的话

   • ✅ 正确："测试覆盖率 ≥ 80%，通过所有 lint 检查"
   • ❌ 错误："保持代码整洁"