5.8 KiB
项目维护与上下文治理
目标
仓库本身是跨 session、跨设备、跨 agent 的唯一持久事实源。聊天记录可以很长，但任何会影响后续工作的决定都不能只存在于聊天中；同时，常驻上下文不能退化成聊天流水账。
所有维护遵守奥卡姆剃刀：选择能完整满足已验证需求的最简单方案。没有当前消费者、实测瓶颈或重复问题时，不增加抽象、服务、拓扑、hook 或“以后可能用到”的框架。
事实分层
| 内容 | 文件 | 维护方式 |
|---|---|---|
| 每次都必须遵守的规则 | AGENTS.md |
保持短、明确、无冲突，最多 200 行 |
| 当前产品事实与长期决定 | docs/project-memory.md |
就地更新，最多 200 行且不超过 12 KB |
| 当前阶段、下一步和阻塞项 | docs/status.md |
就地更新，最多 120 行且不超过 8 KB |
| 当前可验收需求 | docs/需求理解.md |
修改现行规范；变更历史交给 Git |
| 架构取舍与原因 | docs/adr/ |
状态化管理；新决定 supersede 旧 ADR |
| 可复核的证据、保留候选与验收门槛 | docs/research/ |
标注日期、来源和适用边界，过时结论要更新或标记 |
| 已完成工作的时间线 | commit、PR、issue | 不复制进常驻 memory |
每个事实只设一个权威归属，顶层文件只索引，不复制深层正文。一次检查点的最小真相集只包含后续执行无法安全重建的内容：已接受且仍生效的要求/约束、当前实现与证据边界、下一项可执行工作、真实阻塞或未决项，以及需要继续工作的分支/PR。能从代码、测试、Git 或权威资料廉价恢复的细节不进入常驻快照。
长 Session 检查点
在以下时机更新仓库快照：
- 用户确认或改变产品范围、优先级、约束或工作习惯后，在依赖该结论的设计或实现继续前；
- 一个重要设计、调研结论或验收门槛被接受、推翻或被实测结果修正后；
- 从调研、设计、实现、验证中的一个实质阶段进入下一阶段时；
- 切换分支、提交/更新 PR、agent 交接或任务交接前；
- 长任务可能自动压缩、即将暂停或离开当前 session 前。
检查点应立即修改事实的权威归属文件；只有当前全局快照确实改变时才同步修改 project-memory.md 或 status.md。不要等到 session 末尾才补写，也不要为每个文件、函数、工具调用或未形成结论的探索建立检查点。
检查点只保存以后仍需要的结论、当前状态、下一步和阻塞项。不要保存原始对话、完整日志、工具输出、临时文件路径、重复的代码结构、可随时重新搜索的常识、过程性 TODO 流水账或已经在其他规范中存在的内容。
恢复上下文时按以下顺序读取：AGENTS.md、docs/project-memory.md、docs/status.md、相关需求/ADR/调研，然后检查当前分支、git status、最近 commit 和 PR 状态。任何摘要与仓库冲突时，以当前代码、测试和正式文档为准。
清理规则
- 新事实与旧事实冲突时，在同一变更中替换或删除旧内容。
project-memory.md达到约 80% 上限时，先合并同类条目并删除可从代码或 Git 重新发现的内容。- 需求文档保持单一现行版本，不在末尾无限追加确认记录。
- 调研结论失效时更新正文并保留“最后验证日期”；只有仍有历史解释价值的决策才进入 ADR。
- 已完成的临时计划从
status.md删除，由合并后的 PR 和 commit 保存历史。 - 每个重要 PR 都检查文档是否互相矛盾、链接是否仍有效、memory/status 是否仍代表当前事实。
验证节奏
- 迭代中运行能覆盖当前改动的最小定向检查；同一未变化路径已经通过的昂贵检查不因相邻小改动自动失效。
- 完整测试套件、真实浏览器矩阵、长时稳定性、网络整形、跨设备和部署验证按一个完整候选或验收阶段批量运行。只有相关媒体路径、协议、配置、依赖、环境或验收门槛改变，或者上次结果失败/含糊时才重跑对应证据。
- 文档改动默认只运行 Markdown/链接/whitespace/diff 检查；不为与运行时代码无关的改动重跑 npm 全套或媒体基准。
- 在
status.md、调研或 ADR 中记录昂贵验证对应的 commit、环境、结果和适用边界，PR 可以引用该记录，使后续工作能判断证据是否仍有效，而不是机械重跑。 - 发布、安全边界、数据库迁移和部署切换仍按其风险执行必要的最终门禁；“批量验证”不是跳过会被当前变更影响的检查。
在线调研规则
非平凡的设计、实现和 bug 修复先读仓库，再查当前的一手资料。优先级为规范/官方文档、官方源码与维护者说明、原始论文，然后才是高质量社区复现与运行经验。安全、网络协议、浏览器能力、依赖版本和云服务行为属于易变化信息，必须按当前日期重新验证。
调研输出应说明问题、来源日期、已证实事实、推断、候选方案、许可证、适用边界和最终采用理由。不要把搜索结果原样堆进常驻上下文。
自动化
.githooks/pre-commit和 CI 调用scripts/check-project-state.sh；原生 Windows 可运行等价的scripts/check-project-state.ps1。两份入口共享scripts/required-project-paths.txt，检查 whitespace、必需文件、Git 跟踪状态和上下文文件上限。.github/workflows/repository-hygiene.yml在 push/PR 上运行 tracked POSIX 入口。- hook 只做快速、确定、可复现的检查；需要工程判断的内容留给评审和测试。
- 新脚本必须有明确当前用途、跨平台入口、失败信息和 CI 调用方。没有现实使用者的 hook 或框架不进入仓库。