# Agents Writer Maintain

> AGENTS.md 维护与迭代 — 版本管理、反馈闭环、持续改进，确保 AGENTS.md 随项目演进而保持有效

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

---


# ⑤ 迭代维护

> AGENTS.md 不是一次性交付品，它需要随项目一起演进。superpowers 的 AGENTS.md 经过 628 次 commit 才达到今天的成熟度。

## 任务目标

管理 AGENTS.md 的版本演进，收集使用反馈，持续优化文档质量和触发效率。

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

```
□ AGENTS.md 已通过阶段 4 的门禁验收
□ 已确认交付（用户确认使用）
□ 已知当前版本号
```

---

## 维护工作流

### 场景 1: 版本更新

当项目发生以下变化时，AGENTS.md 需要更新：

| 项目变化 | AGENTS.md 影响 | 触发动作 |
|---------|---------------|---------|
| 技术栈变更 | 命令、路径、架构章节需要更新 | 更新对应章节 + 版本号 minor |
| 新增功能模块 | 行为规则中允许/禁止列表需要扩展 | 更新功能边界 + 版本号 minor |
| 团队规模变化 | 多 Agent 协作规则需要调整 | 更新角色分工 + 版本号 minor |
| 安全要求变更 | 红线和安全规则需要调整 | 更新安全检查 + 版本号 major 或 minor |
| 项目阶段变更 | 工作流和门禁严格程度需要调整 | 全面审查 + 版本号 major |
| 用户反馈优化 | 触发条件、Token 效率、可读性 | 局部优化 + 版本号 patch |

**版本号规则**：
```
vX.Y.Z
│ │ │
│ │ └── patch: 小修改（修复错别字、优化描述、调整示例）
│ └──── minor: 新增内容（新规则、新章节、新命令）
└────── major: 重大重构（结构重写、方法论变更、门禁体系重构）
```

**更新命令**：
```bash
# 更新版本号
# patch 更新
sed -i 's/version: v1\.0\.0/version: v1.0.1/' AGENTS.md
# minor 更新
sed -i 's/version: v1\.0\.0/version: v1.1.0/' AGENTS.md
# major 更新
sed -i 's/version: v1\.0\.0/version: v2.0.0/' AGENTS.md

# 更新版本历史
# 在版本历史章节底部添加新行
```

**推荐做法**：在 AGENTS.md 末尾维护版本历史表格：

```markdown
## 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|---------|
| v1.1.0 | 2026-07-15 | 新增安全检查章节，更新红线规则 |
| v1.0.0 | 2026-07-05 | 初始版本 |
```

---

### 场景 2: 反馈闭环

用户在使用 AGENTS.md 过程中会发现问题。建立反馈闭环确保持续改进。

**反馈来源**：
1. **用户直接反馈** — "这里规则不太对"、"触发条件不够准确"
2. **用户修改** — 用户直接修改了 AGENTS.md，对比 diff 理解需求
3. **行为观察** — Agent 按 AGENTS.md 执行时出现不符合预期的行为
4. **性能指标** — Token 消耗过高或触发率不理想

**反馈处理流程**：
```
收到反馈
    │
    ▼
评估影响范围
    ├── 小修改（错别字/单条规则）→ 直接修改 → patch 版本
    ├── 中修改（新增规则/章节）→ 修改 → 门禁抽查 → minor 版本
    └── 大修改（结构/方法论重调）→ 从阶段 2 设计重新开始 → major 版本
```

---

### 场景 3: 描述优化

AGENTS.md 的 description 字段是触发机制的核心。如果发现 Agent 在应该触发的时候没有触发，或者在不应该触发的时候触发了，需要优化描述。

**优化方法**：

1. **分析触发失败模式**：
   ```
   应该触发但没触发 → description 太窄，缺少触发场景
   不应触发但触发了 → description 太宽，边界不清晰
   ```

2. **根据失败模式调整描述**：
   ```
   太窄 → 增加触发场景描述和关键词
   太宽 → 增加排除条件（"但不要用于..."）
   ```

3. **验证**：想象 3 个应该触发和 3 个不应触发的场景，测试 description 是否能正确区分。

---

### 场景 4: Token 优化

如果 AGENTS.md 太大导致每次对话加载成本过高：

**优化策略**（从高收益到低收益排序）：

1. **拆分无关内容**：将不常用的章节移到单独的参考文件
2. **合并重复规则**：同一件事只说一次
3. **压缩示例**：示例保持 1 个，删除冗余
4. **缩短"为什么"**：每条规则的 why 控制在 1 句话
5. **使用表格**：表格比段落节省约 30% Token
6. **删除冗余门禁**：去除过于细碎的门禁，保留关键门禁

**目标**：
- 核心 AGENTS.md ≤ 500 行
- 描述 ≤ 150 字
- 每条规则 ≤ 3 行

---

## 维护日志

每次维护操作后记录维护日志：

```yaml
# 维护日志 (maintenance-log.yaml)
date: 2026-07-15
version: v1.1.0
type: minor
reason: 新增安全检查章节
changes:
  - 新增: 安全检查章节（G4 相关规则）
  - 修改: 红线章节增加了 2 条新红线
  - 优化: Token 效率优化，合并了 2 条重复规则
review:
  gates_passed: 21/21
  notes: 新增章节后重新验收全部通过
```