morning-start ⑤ 迭代维护
AGENTS.md 不是一次性交付品，它需要随项目一起演进。superpowers 的 AGENTS.md 经过 628 次 commit 才达到今天的成熟度。
任务目标
管理 AGENTS.md 的版本演进，收集使用反馈，持续优化文档质量和触发效率。
进入前必须完成
□ AGENTS.md 已通过阶段 4 的门禁验收
□ 已确认交付（用户确认使用）
□ 已知当前版本号
维护工作流
场景 1: 版本更新
当项目发生以下变化时，AGENTS.md 需要更新：
| 项目变化 | AGENTS.md 影响 | 触发动作 |
|---|---|---|
| 技术栈变更 | 命令、路径、架构章节需要更新 | 更新对应章节 + 版本号 minor |
| 新增功能模块 | 行为规则中允许/禁止列表需要扩展 | 更新功能边界 + 版本号 minor |
| 团队规模变化 | 多 Agent 协作规则需要调整 | 更新角色分工 + 版本号 minor |
| 安全要求变更 | 红线和安全规则需要调整 | 更新安全检查 + 版本号 major 或 minor |
| 项目阶段变更 | 工作流和门禁严格程度需要调整 | 全面审查 + 版本号 major |
| 用户反馈优化 | 触发条件、Token 效率、可读性 | 局部优化 + 版本号 patch |
版本号规则：
vX.Y.Z
│ │ │
│ │ └── patch: 小修改（修复错别字、优化描述、调整示例）
│ └──── minor: 新增内容（新规则、新章节、新命令）
└────── major: 重大重构（结构重写、方法论变更、门禁体系重构）
更新命令：
# 更新版本号
# 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 末尾维护版本历史表格：
## 版本历史
| 版本 | 日期 | 变更说明 |
|------|------|---------|
| v1.1.0 | 2026-07-15 | 新增安全检查章节，更新红线规则 |
| v1.0.0 | 2026-07-05 | 初始版本 |
场景 2: 反馈闭环
用户在使用 AGENTS.md 过程中会发现问题。建立反馈闭环确保持续改进。
反馈来源：
- 用户直接反馈 — "这里规则不太对"、"触发条件不够准确"
- 用户修改 — 用户直接修改了 AGENTS.md，对比 diff 理解需求
- 行为观察 — Agent 按 AGENTS.md 执行时出现不符合预期的行为
- 性能指标 — Token 消耗过高或触发率不理想
反馈处理流程：
收到反馈
│
▼
评估影响范围
├── 小修改（错别字/单条规则）→ 直接修改 → patch 版本
├── 中修改（新增规则/章节）→ 修改 → 门禁抽查 → minor 版本
└── 大修改（结构/方法论重调）→ 从阶段 2 设计重新开始 → major 版本
场景 3: 描述优化
AGENTS.md 的 description 字段是触发机制的核心。如果发现 Agent 在应该触发的时候没有触发，或者在不应该触发的时候触发了，需要优化描述。
优化方法：
分析触发失败模式：
应该触发但没触发 → description 太窄，缺少触发场景 不应触发但触发了 → description 太宽，边界不清晰根据失败模式调整描述：
太窄 → 增加触发场景描述和关键词 太宽 → 增加排除条件（"但不要用于..."）验证：想象 3 个应该触发和 3 个不应触发的场景，测试 description 是否能正确区分。
场景 4: Token 优化
如果 AGENTS.md 太大导致每次对话加载成本过高：
优化策略（从高收益到低收益排序）：
- 拆分无关内容：将不常用的章节移到单独的参考文件
- 合并重复规则：同一件事只说一次
- 压缩示例：示例保持 1 个，删除冗余
- 缩短"为什么"：每条规则的 why 控制在 1 句话
- 使用表格：表格比段落节省约 30% Token
- 删除冗余门禁：去除过于细碎的门禁，保留关键门禁
目标：
- 核心 AGENTS.md ≤ 500 行
- 描述 ≤ 150 字
- 每条规则 ≤ 3 行
维护日志
每次维护操作后记录维护日志：
# 维护日志 (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: 新增章节后重新验收全部通过