5 maintain

Skill morning-start/agent-skills/process/agents-writer/skills/5-maintain

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

Install

npx -y skills add morning-start/agent-skills --skill 5-maintain

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.0 KB, ~1.8k tokens by cl100k_base, as published. Nobody here has run it

⑤ 迭代维护

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: 重大重构（结构重写、方法论变更、门禁体系重构）

更新命令：

# 更新版本号
# 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: 新增章节后重新验收全部通过

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.