4.0 KiB
4.0 KiB
变更影响矩阵
遇到不确定"这次改动要同步哪些文件"时查这张表。两个方向都要查：补漏（加到哪些文件）+ 防膨胀（应该从哪些文件删）。
反向：哪些信息该从 CLAUDE.md / 记忆里删除
CLAUDE.md / AGENTS.md 不是变更日志。下面这些反模式发现了就删 / 迁：
| 反模式 | 处理 |
|---|---|
| "X 时刻起 Y 功能上线，详见 docs/Z.md" 形式的 blockquote | 删除——指针角色已经被「深入文档」指针表占掉，叙事归 git log / /changelog / docs/CHANGES.md |
| 在 CLAUDE.md 里抄 docs/ 已有的详细机制 / 数据流 / 评分公式 | 删除——AI 改到这块自然会读 docs，CLAUDE.md 只留"边界规则" |
| 已经稳定 ≥ 7 天的"新功能上线"叙事 | 该融入项目概览的融入；纯历史的删 |
| 一次性事故的复盘细节（"X 时 Y 服务挂了 30min 因为 Z"） | 留 1 行红线规则（"不要再裸跑 systemctl stop X"），事故详情归 docs/PLAYBOOK.md 或删 |
| 已被新版本取代的"中间态"叙事（"5/6 改了 X，5/8 又改成 Y"） | 只留最终态规则；中间历史删 |
| 单条 memory > 100 行 + 全是事故复盘 | 提炼成一条 ≤ 30 行的"规则 + Why + How to apply"；多余的删 |
| 记忆条目里"已被 X 取代" / "已废弃" / "保留作历史" 字样 | 99% 真的可以删，docs 已经是权威 |
判断标准：这条信息在下次 AI 写代码时如果没看到，会犯错吗？ 不会就删 / 迁。
代码层变更 → 文档层变更
| 本次对话发生的事 | 要改的文件(按受众) |
|---|---|
| 新增 API / 路由 | 项目根 markdown 路由清单 · docs/integration-guide.md API 速查表 · docs/architecture.md Routes 小节 |
| 新增 / 改名 环境变量 | 项目根 markdown 环境变量表 · docs/operator-runbook.md 环境变量章节 · docs/integration-guide.md(如果下游要配) |
| 新增数据库表 / 列 | 项目根 markdown 数据库表 · docs/architecture.md Data Model |
| 新增 / 改动 用户流程 | 项目根 markdown 用户流程 · README 相关命令行示例 · docs/handoff.md What Exists Today |
| 新增大特性(能跨多文件) | 以上全部 + docs/architecture.md 新增章节 + docs/handoff.md 已完成清单 |
| 新增术语 / 改命名 | docs/integration-guide.md 术语表(如果有)+ 全局搜索旧术语替换 |
| 部署参数 / 基础设施变化 | docs/operator-runbook.md · 项目根 markdown 部署章节 |
| 下游项目接入方式变化 | 下游项目的 docs/<integration>.md · 上游项目的 integration-guide.md |
记忆层变更
| 情况 | 处理方式 |
|---|---|
| 过期事实 | 改记忆文件,同时更新索引(如 MEMORY.md)的 description |
| 相对时间("今天"、"最近") | 全部转成绝对日期(2026-04-29 而非"今天") |
| 重复记录(多条说同一件事) | 合并为一条,改索引 |
| 已完成的待办 | 删除——知识库不是历史档案 |
| 推翻的决策 | 删除旧条目,留新决策 |
| 跨会话只用一次的临时上下文 | 删除 |
跨项目影响检查
最容易漏改的场景:
- 上游 API 变了 → 下游 SDK 文档:协议变化必须两边对齐
- 共享子域 / 路由 / 环境变量改了 → 所有 consumer 项目的 setup 文档
- 认证中台变更 → 所有接入应用的 integration guide
- 公共组件 / 基础设施 升级 → 各项目的 operator-runbook 提及版本号的地方
判断方法:这次改的东西有没有 SDK、子域、共享配置、跨进程协议?有就要在所有依赖项目里搜一遍提到这件事的文档。
文档结构通用约定
新增一个能力(API、flow、特性)的标准动作是四处都补:
- integration-guide / 外部视角文档:怎么用(curl / SDK 示例 / 错误码)
- architecture:怎么工作(数据流、状态机、设计取舍)
- runbook:怎么运维(冒烟命令、故障排查、环境变量)
- handoff / CHANGELOG:已完成
API 速查表、环境变量表、术语表是高频查询的结构化信息,必须保持"所见即最新"。