08 - 运维与持续进化体系设计

1. 定位

让整套体系保持生命力，而不是配好后逐渐废弃。

核心认知：体系的价值不在于初始配置，而在于持续迭代。 一个随使用越来越好的体系，比一个一开始就"完美"但不进化的体系强得多。

2. Git 分支策略

项目代码

main（保护分支）
  └── feature/xxx（AI 的所有操作在此分支）
        └── 完成后 PR 合并到 main

规则：

• main 分支禁止直接推送 — 所有变更通过 feature 分支 + PR
• AI 开始任务前先创建分支：git checkout -b feature/task-name
• 每个独立功能一个分支，不混合
• 合并后删除 feature 分支

体系配置

体系本身的配置文件（CLAUDE.md、settings.json、Skills、Hooks）也用 git 管理：

这些文件应该被 Git 追踪：
  ✓ CLAUDE.md
  ✓ .claude/settings.json
  ✓ .claude/commands/*.md
  ✓ .claude/skills/*/SKILL.md
  ✓ .claude/hooks/*.sh
  ✓ .mcp.json
  ✓ docs/approved-deps.md
  ✓ docs/adr/*.md

这些文件应该在 .gitignore 中：
  ✗ CLAUDE.local.md
  ✗ .claude/settings.local.json
  ✗ ~/.claude/projects/*/memory/（Auto Memory，机器本地，不入 git）

3. 依赖管控

流程

AI 想引入新依赖
    │
    ├── 在 docs/approved-deps.md 白名单中？
    │     ├── 是 → 直接使用
    │     └── 否 → 告知人，等待评估
    │
    └── 人评估后
          ├── 批准 → 添加到白名单 + 使用
          └── 拒绝 → 给出替代方案

评估标准

新依赖的准入门槛：

1. 必要性 — 原生方法或现有依赖能否解决？
2. 维护状态 — GitHub stars、最近更新时间、issue 响应速度
3. 包体积 — bundlephobia.com 检查大小
4. 安全性 — npm audit 无已知漏洞
5. 许可证 — MIT/Apache 2.0 优先

定期审查

每月运行一次：

# 检查过期依赖
npm outdated

# 安全审计
npm audit

# 未使用依赖检测
npx depcheck

4. 持续进化闭环

使用体系进行开发
    │
    ├── 记录 AI 犯的错 → 更新 CLAUDE.md "常见陷阱"
    │
    ├── 发现 Hook 漏网 → 加强 Hook 规则
    │
    ├── 发现重复性 prompt → 沉淀为新 Skill 或 Command
    │
    ├── 发现 MCP 不够用/太多 → 调整 MCP 配置
    │
    └── 发现流程卡点 → 优化对应模块

进化触发条件

信号	进化动作
同一个 prompt 写了 3 次以上	沉淀为 Command 或 Skill
AI 犯了相同的错 2 次	加入 CLAUDE.md 常见陷阱
Hook 没拦住一个应该拦的操作	更新 Hook 正则规则
某个 MCP 连续 2 周没用过	从 .mcp.json 移除
新加的 MCP 使用频率很高	从临时添加变为常驻配置
某个 Skill 执行效果不好	重写 Skill 指令
CLAUDE.md 超过 150 条指令	清理过时条目，合并重复项
核心工具链发布新版本	走版本追踪流程（doc-20 §7）
看到有价值的外部文章/教程	走 /absorb 吸收流程（doc-20 §3）
/retro 中发现可泛化的经验	记录到待吸收清单（doc-20 §5）
Auto Memory 中同一模式出现 3+ 次	提升为 CLAUDE.md 正式规则

战略级触发器

上面的触发器是战术级的（逐条匹配）。以下是需要整体反思的信号：

信号	说明	行动
超过 50% 会话时间在调试而非构建	架构可能有系统性问题	专门开一个探索会话分析根因，考虑重构
同一模块连续 3 次出 Bug	该模块的抽象或边界有问题	补测试 + 重新审视模块设计
CLAUDE.md 指令超过 100 条	规则膨胀，AI 可能无法全部遵守	清理 + 合并 + 将细节规则下沉到 Skill
新功能开发速度明显变慢	可能是技术债累积或架构耦合	运行 /health-report，优先处理变更热点
每次改动都需要改 5+ 文件	模块耦合过高	审视模块边界，考虑解耦重构

规则老化机制

规则不是只增不减的。每季度执行一次规则清理：

清理流程：
1. 逐条审阅 CLAUDE.md 的规则
2. 对每条规则问："过去 3 个月，这条规则阻止过哪个具体错误？"
3. 回答不出来 → 标记为待删除候选
4. 候选规则保留一个月观察，确认无用后移除

同样适用于：
- Skills：连续 4 周无人调用 → 移除
- Hooks：连续 2 个月无拦截记录 → 评估是否仍需要
- MCP：连续 2 周无调用 → 从 .mcp.json 移除

完整的月度 + 季度检查清单详见 §7 健康检查清单。

5. 版本化管理

体系本身的重大变更也应该有 commit 记录：

# 体系变更的 commit 前缀
chore(claude): update CLAUDE.md - add prisma pitfall
chore(hooks): add pre-bash firewall for docker commands
chore(skills): add /debug skill
chore(mcp): remove unused memory server
chore(deps): update approved dependencies list

这样可以通过 git log 追溯体系的演进历史：

git log --oneline --grep="chore(claude)"
git log --oneline --grep="chore(hooks)"

6. 故障恢复

常见故障与处理

故障	症状	处理
CLAUDE.md 规则冲突	AI 输出矛盾的行为	检查规则优先级，删除冲突条目
Hook 误阻断	正常命令被拦截	临时放宽 Hook 正则，事后修正
Hook 全部失效	格式化/拦截不触发	检查 settings.json 格式和脚本权限
MCP 连接失败	会话启动报错	claude mcp remove 临时移除，事后排查
上下文严重退化	AI 忘记所有规则	/clear 开新会话
settings.json 损坏	Claude Code 启动异常	从 git 恢复：git checkout -- .claude/settings.json

紧急降级方案

如果整套体系出了问题，可以逐级降级：

完整体系（全部正常）
    ↓ MCP 出问题
Level 1：关闭所有 MCP，依赖内置工具
    ↓ Hooks 出问题
Level 2：清空 hooks 配置，手动运行格式化和测试
    ↓ Skills 出问题
Level 3：直接用 prompt 代替 Skill
    ↓ CLAUDE.md 出问题
Level 4：清空 CLAUDE.md，用最基本的提示词工作

最低保障：即使全部配置失效，Claude Code 本身的能力不受影响，只是失去了自动化增强。

6.5 新兴生态：插件与分发

概念

Claude Code 正在发展插件（Plugins）生态，将 Skills + Hooks + Agents + MCP 打包为可安装单元，实现跨项目复用和社区分发。

插件结构

.claude-plugin/
├── plugin.json          # 元数据（名称、版本、描述、兼容性）
├── skills/              # 捆绑的 Skills
├── agents/              # 捆绑的自定义子代理
└── hooks/               # 捆绑的 Hook 脚本

评估原则

引入第三方插件前，评估四个维度：

维度	问题
必要性	体系内机制（Skills + MCP）能否解决？
稳定性	插件是否经过充分测试？版本是否活跃维护？
上下文成本	插件注入了多少额外 token？对性能影响多大？
维护责任	插件更新时，你的配置需要同步调整吗？

当前策略

保守观望。 插件生态尚在早期，优先使用体系内机制：

需要可复用的 AI 指令？  → Skills
需要自动化守卫？       → Hooks
需要外部数据源？       → MCP
需要专业化代理？       → 自定义子代理

以上都不够用时 → 考虑插件

等生态成熟、社区建立了质量标准后，再逐步引入高价值插件。

7. 健康检查清单（月度 + 季度）

每月约 40 分钟，每季度另需 30 分钟。建议加入日历提醒。

月度检查

体系运营

□ CLAUDE.md
  - 指令数是否超过 150 条？
  - "常见陷阱"中有没有过时条目？
  - 架构描述是否和实际代码一致？

□ Skills & Commands
  - 哪些 Skill 最近没用过？是否需要移除？
  - 有没有新的重复性工作应该沉淀为 Skill？

□ Hooks
  - 有没有被误拦的正常操作？调整正则
  - 有没有漏拦的危险操作？加强规则

□ MCP
  - 同时激活的 MCP 是否超过 5 个？
  - 有没有长期未用的 MCP？移除

□ 外部知识吸收（详见 [doc-20](./20-external-evolution.md) §8）
  - 版本追踪：核心工具链有无重要更新？
  - 定期搜索：本月重点关注 1-2 个主题
  - 待吸收清单处理：项目实战中积累的泛化经验

□ 依赖
  - 运行 npm outdated / npm audit
  - 白名单是否需要更新？

□ settings.json
  - 权限规则是否需要调整？
  - 有没有操作频繁弹确认但其实是安全的？→ 加入 allow

文档体系

□ 配置示例一致性
  - 文档中的 CLAUDE.md 模板是否与实际使用的格式一致？
  - Hooks 脚本示例是否与 .claude/hooks/ 中的脚本同步？
  - settings.json 示例是否反映当前实际配置？
  - .mcp.json 示例是否与当前 MCP 配置匹配？

□ 交叉引用有效性
  - README.md 索引表是否覆盖所有文档？（新增文档后容易遗漏）
  - 文档间的相对链接是否可访问？（重命名或移动后容易断裂）
  - 编号是否连续？（删除文档后可能出现断号）

□ 内容时效性
  - "常见陷阱"和"反模式"是否仍然有效？
  - 流程图和决策树是否反映当前工作流？
  - 示例代码是否能在当前环境下运行？

季度检查

规则老化清理（详见 §4 规则老化机制）

- 逐条审阅 CLAUDE.md 规则，删除已无效条目
- Skills 连续 4 周无调用 → 移除
- Hooks 连续 2 个月无拦截 → 评估是否仍需要
- MCP 连续 2 周无调用 → 从 .mcp.json 移除

文档深度审查

□ 技术栈版本
  - React / Next.js / Node.js 版本引用是否过时？
  - Prisma / TypeScript 版本相关说明是否需要更新？
  - 依赖白名单中的包是否有重大版本变化？

□ 文档体量控制
  - 单篇文档是否超过 500 行？（超过则考虑拆分）
  - 文档总量是否仍在可维护范围内？
  - 是否有内容重复分布在多篇文档中？（合并或指定唯一来源）

□ 脚手架模板同步
  - 09-脚手架设计中的模板是否与最新实践一致？
  - init/check/takeover 三模式的说明是否与脚本实际行为匹配？

□ 实用性验证
  - 07-操作手册中的日常流程是否仍然是你实际使用的流程？
  - 12-效率最佳实践和 15-Prompt 工程实战中的技巧是否有新积累？
  - 是否有文档从未被翻阅过？（考虑合并或删除）

检查结果处理

发现问题	处理方式
配置示例过时	直接更新文档，同步记录到 CHANGELOG.md
交叉引用断裂	修复链接，检查是否有其他文档引用了同一目标
技术栈版本过时	评估影响范围，批量更新相关文档
单篇超过 500 行	拆分为主文档 + 附录，或提取实现细节到独立文件
内容重复	保留一处为"唯一来源"，其他处改为引用链接
文档从未使用	先标记观察一个周期，确认无用后合并或删除

8. 与其他子系统的关系

运维与进化体系是元体系 — 它管理其他所有子系统的健康：

运维体系
  ├── 管理 → CLAUDE.md 的规则数量和有效性
  ├── 管理 → Skills 的使用频率和效果
  ├── 管理 → Hooks 的拦截准确性
  ├── 管理 → MCP 的必要性和稳定性
  ├── 管理 → 文档的同步性
  ├── 管理 → 依赖的安全性和时效性
  └── 驱动 → 外部知识吸收（doc-20）

---

关联文档：20-体系外部进化机制（外部进化闭环，补全本文档的外部知识吸收能力）