Piik/docs/maintenance.md

项目维护与上下文治理

目标

仓库本身是跨 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

长 Session 检查点

在以下时机更新仓库快照：

• 用户确认或改变产品范围、优先级、约束或工作习惯后；
• 一个重要设计被接受、推翻或被实测结果修正后；
• 长任务即将发生上下文压缩、交接或暂停前；
• 一个功能分支准备提交或 PR 前。

检查点只保存以后仍需要的结论、当前状态、下一步和阻塞项。不要保存原始对话、完整日志、工具输出、临时文件路径、重复的代码结构、可随时重新搜索的常识或已经在其他规范中存在的内容。

恢复上下文时按以下顺序读取：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 是否仍代表当前事实。

在线调研规则

非平凡的设计、实现和 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 或框架不进入仓库。