From 38c270d4da87cc695181766568654895420929f4 Mon Sep 17 00:00:00 2001 From: AAA <35992542+TNTcraftHIM@users.noreply.github.com> Date: Wed, 19 Aug 2026 09:06:32 +0800 Subject: [PATCH] docs: harden context checkpoints and validation cadence --- AGENTS.md | 9 ++++---- docs/maintenance.md | 25 +++++++++++++++++------ docs/research/agent-context-governance.md | 15 +++++++++----- 3 files changed, 33 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1d81fe2..09a57cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,10 +13,9 @@ ## Repository Knowledge - At the start of substantial work, read `docs/project-memory.md`, `docs/status.md`, and the relevant requirement, ADR, and research documents. -- Keep durable project decisions, requirements, research, code, and agent configuration inside this repository and Git-tracked. -- Do not leave required project context only in chat history, a user home directory, or an untracked scratch file. -- Treat `docs/project-memory.md` and `docs/status.md` as bounded current snapshots, not append-only journals. Replace or remove stale facts and use Git history for the timeline. -- Update project memory when a durable decision changes, before context compaction on long tasks, and at task handoff. Use `docs/adr/` for architecture decisions and tradeoffs. +- Treat the Git-tracked repository as the persistent source of truth. Before dependent work continues, write every accepted requirement or priority, design change, durable research conclusion or retained candidate, actionable TODO or blocker, and material status change to its owning repository document; chat alone is not a durable record. +- Maintain one minimal truth set: current snapshots in `docs/project-memory.md` and `docs/status.md`, current requirements and design in their specifications, decisions in `docs/adr/`, evidence in `docs/research/`, and the timeline in Git history. Replace stale facts in place and do not duplicate detailed content into this file. +- Checkpoint that truth set at material phase boundaries, after accepted decisions change, at branch/PR or agent handoff, and before likely context compaction or a long pause. After compaction or resumption, re-read the snapshots and inspect Git state before continuing. - Keep `docs/README.md` current when documentation is added, moved, or superseded. ## Research Before Changes @@ -37,7 +36,6 @@ - Keep this root file concise and stable; put specialized rules in the closest relevant directory only when that code exists. - Never store raw transcripts, large logs, generated summaries, temporary plans, or facts that can be cheaply rediscovered in always-loaded memory. -- On a long session, checkpoint accepted decisions and current state before relying on automatic context compression. After compression or resumption, re-read the current snapshots and inspect Git state. - When a fact changes, update it in place and remove conflicting text in the same change. Do not preserve obsolete guidance merely for history. ## Security @@ -59,6 +57,7 @@ - Keep changes scoped and preserve unrelated user work. - Prefer the smallest proven extension point; do not add speculative frameworks, hooks, or abstractions without a current consumer. - Add automated tests in proportion to behavioral risk. For realtime media changes, also document the manual network and browser matrix used. +- Batch validation by risk and phase: run narrow checks while iterating, and run expensive full suites, browser matrices, endurance tests, or deployment checks only at an acceptance boundary or when a relevant change invalidates prior evidence. Documentation-only or unrelated changes do not invalidate media-path evidence. - Use comments for non-obvious rationale, invariants, protocol constraints, and workarounds; do not narrate obvious code. - Use WebRTC statistics and reproducible measurements for latency, bitrate, candidate type, packet loss, encode time, and quality limitations. Do not claim performance from assumptions alone. - Keep repository scripts and hooks cross-platform, deterministic, fast, and runnable in CI. A hook must call a tracked script rather than hide project logic in machine-local configuration. diff --git a/docs/maintenance.md b/docs/maintenance.md index 71ec046..beb40e0 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -15,19 +15,24 @@ | 当前阶段、下一步和阻塞项 | `docs/status.md` | 就地更新，最多 120 行且不超过 8 KB | | 当前可验收需求 | `docs/需求理解.md` | 修改现行规范；变更历史交给 Git | | 架构取舍与原因 | `docs/adr/` | 状态化管理；新决定 supersede 旧 ADR | -| 可复核的外部证据 | `docs/research/` | 标注日期、来源和适用边界，过时结论要更新或标记 | +| 可复核的证据、保留候选与验收门槛 | `docs/research/` | 标注日期、来源和适用边界，过时结论要更新或标记 | | 已完成工作的时间线 | commit、PR、issue | 不复制进常驻 memory | +每个事实只设一个权威归属，顶层文件只索引，不复制深层正文。一次检查点的最小真相集只包含后续执行无法安全重建的内容：已接受且仍生效的要求/约束、当前实现与证据边界、下一项可执行工作、真实阻塞或未决项，以及需要继续工作的分支/PR。能从代码、测试、Git 或权威资料廉价恢复的细节不进入常驻快照。 + ## 长 Session 检查点 在以下时机更新仓库快照： -- 用户确认或改变产品范围、优先级、约束或工作习惯后； -- 一个重要设计被接受、推翻或被实测结果修正后； -- 长任务即将发生上下文压缩、交接或暂停前； -- 一个功能分支准备提交或 PR 前。 +- 用户确认或改变产品范围、优先级、约束或工作习惯后，在依赖该结论的设计或实现继续前； +- 一个重要设计、调研结论或验收门槛被接受、推翻或被实测结果修正后； +- 从调研、设计、实现、验证中的一个实质阶段进入下一阶段时； +- 切换分支、提交/更新 PR、agent 交接或任务交接前； +- 长任务可能自动压缩、即将暂停或离开当前 session 前。 -检查点只保存以后仍需要的结论、当前状态、下一步和阻塞项。不要保存原始对话、完整日志、工具输出、临时文件路径、重复的代码结构、可随时重新搜索的常识或已经在其他规范中存在的内容。 +检查点应立即修改事实的权威归属文件；只有当前全局快照确实改变时才同步修改 `project-memory.md` 或 `status.md`。不要等到 session 末尾才补写，也不要为每个文件、函数、工具调用或未形成结论的探索建立检查点。 + +检查点只保存以后仍需要的结论、当前状态、下一步和阻塞项。不要保存原始对话、完整日志、工具输出、临时文件路径、重复的代码结构、可随时重新搜索的常识、过程性 TODO 流水账或已经在其他规范中存在的内容。 恢复上下文时按以下顺序读取：`AGENTS.md`、`docs/project-memory.md`、`docs/status.md`、相关需求/ADR/调研，然后检查当前分支、`git status`、最近 commit 和 PR 状态。任何摘要与仓库冲突时，以当前代码、测试和正式文档为准。 @@ -40,6 +45,14 @@ - 已完成的临时计划从 `status.md` 删除，由合并后的 PR 和 commit 保存历史。 - 每个重要 PR 都检查文档是否互相矛盾、链接是否仍有效、memory/status 是否仍代表当前事实。 +## 验证节奏 + +- 迭代中运行能覆盖当前改动的最小定向检查；同一未变化路径已经通过的昂贵检查不因相邻小改动自动失效。 +- 完整测试套件、真实浏览器矩阵、长时稳定性、网络整形、跨设备和部署验证按一个完整候选或验收阶段批量运行。只有相关媒体路径、协议、配置、依赖、环境或验收门槛改变，或者上次结果失败/含糊时才重跑对应证据。 +- 文档改动默认只运行 Markdown/链接/whitespace/diff 检查；不为与运行时代码无关的改动重跑 npm 全套或媒体基准。 +- 在 `status.md`、调研或 ADR 中记录昂贵验证对应的 commit、环境、结果和适用边界，PR 可以引用该记录，使后续工作能判断证据是否仍有效，而不是机械重跑。 +- 发布、安全边界、数据库迁移和部署切换仍按其风险执行必要的最终门禁；“批量验证”不是跳过会被当前变更影响的检查。 + ## 在线调研规则 非平凡的设计、实现和 bug 修复先读仓库，再查当前的一手资料。优先级为规范/官方文档、官方源码与维护者说明、原始论文，然后才是高质量社区复现与运行经验。安全、网络协议、浏览器能力、依赖版本和云服务行为属于易变化信息，必须按当前日期重新验证。 diff --git a/docs/research/agent-context-governance.md b/docs/research/agent-context-governance.md index 4d9ef4a..49aa395 100644 --- a/docs/research/agent-context-governance.md +++ b/docs/research/agent-context-governance.md @@ -1,6 +1,7 @@ # Agent 上下文与仓库治理调研 - 调研日期：2026-08-18 +- 最后复核：2026-08-19 - 范围：Codex、Claude Code、Hermes Agent 与 GitHub Flow 的官方资料 - 目的：让长 session 和多设备开发可恢复，同时限制常驻上下文膨胀与陈旧事实污染 @@ -8,16 +9,17 @@ ### Codex -Codex 从 Git 根目录向当前工作目录发现 `AGENTS.md`，越接近当前目录的文件优先级越高；默认合并上限为 32 KiB。适合把仓库级不变量放在根文件，把未来模块特有规则放在相邻目录，而不是把所有细节集中到一个无限增长的说明中。 +Codex 从 Git 根目录向当前工作目录发现 `AGENTS.md`，越接近当前目录的文件优先级越高；默认合并上限为 32 KiB。官方还要求规则保持简洁，并建议长任务在重大里程碑后压缩，而不是每轮压缩。因此仓库级不变量应放在根文件，具体流程按需放进维护文档或相邻目录，且同一规则只表达一次。 来源： - [Codex AGENTS.md 官方说明](https://learn.chatgpt.com/docs/agent-configuration/agents-md) - [Codex 项目配置官方说明](https://learn.chatgpt.com/docs/config-file/config-basic) +- [OpenAI 模型指南：精简提示与里程碑压缩](https://developers.openai.com/api/docs/guides/latest-model) ### Claude Code -Claude Code 官方建议项目指令具体、简洁、结构化，单个 `CLAUDE.md` 目标控制在 200 行以内，并定期清理冲突或过时指令。官方还区分“上下文中的建议”和“确定执行的 hook”：必须在固定时机运行的检查应写成 hook。根 `CLAUDE.md` 会在压缩后重新注入；大型读取可以交给独立 subagent，主上下文只接收结论。 +Claude Code 官方建议项目指令具体、简洁、结构化，单个 `CLAUDE.md` 目标控制在 200 行以内，并定期清理冲突或过时指令。根 `CLAUDE.md` 和 auto memory 会在压缩后从磁盘重新注入，而仅存在于对话的指令可能丢失；`MEMORY.md` 只把前 200 行或 25 KB 作为常驻索引，并要求临近上限时合并或删除陈旧内容。官方还区分“上下文中的建议”和“确定执行的 hook”：必须在固定时机运行的机器检查应写成 hook，大型读取可以交给独立 subagent，主上下文只接收结论。 Claude Code 原生读取 `CLAUDE.md`，官方建议已有 `AGENTS.md` 的仓库通过 `@AGENTS.md` 导入，避免复制两份规则。本仓库因此保留一个极小的根 `CLAUDE.md` 作为兼容入口。 @@ -29,7 +31,7 @@ Claude Code 原生读取 `CLAUDE.md`，官方建议已有 `AGENTS.md` 的仓库 ### Hermes Agent -Hermes Agent 的内置 memory 采用硬字符上限，并明确要求容量接近上限时先合并或删除旧条目。官方把“始终需要的关键事实”与“需要时再搜索的历史 session”分开；还明确不应保存原始数据、临时上下文、容易重新发现的信息或已经存在于项目指令中的重复内容。 +Hermes Agent 的内置 memory 采用硬字符上限，并明确要求容量接近上限时先合并或删除旧条目。官方把“始终需要的关键事实”与“需要时再搜索的历史 session”分开；还明确不应保存原始数据、临时上下文、容易重新发现的信息或已经存在于项目指令中的重复内容。其 memory 是 session 启动时的冻结快照，进一步说明跨设备、跨 agent 的项目事实应进入 Git 跟踪的项目文件，而不是机器本地 memory。 Hermes Agent 的开发指南强调保持核心窄小、优先扩展已有接口、避免没有当前使用者的 speculative hook，并要求真实路径验证而不只依赖 mock。这些原则适合约束本项目未来的 agent、hook 和脚本增长。 @@ -48,8 +50,11 @@ GitHub 官方流程是短分支、隔离的完整 commit、push 远端、PR 评 - 根 `AGENTS.md` 最多 200 行，只放跨任务不变量；`.codex/config.toml` 将指令发现预算固定为 32 KiB。 - `CLAUDE.md` 只导入 `AGENTS.md`，不维护第二份规则。 -- `project-memory.md` 是最多 12 KB 的当前事实快照；`status.md` 是当前阶段快照；两者都更新和清理，不追加对话历史。 -- 需求、ADR、调研、代码、测试和 Git/PR 各自承担不同类型的事实，避免同一信息在多个常驻文件里漂移。 +- `project-memory.md` 是最多 12 KB 的当前事实快照；`status.md` 是当前阶段快照；两者只保留最小真相集并就地更新，不追加对话、过程 TODO 或完成时间线。 +- 上下文按层归属：`AGENTS.md` 保存顶级约束与读取触发器；memory/status 保存当前最小快照；现行需求/设计和 ADR 保存已接受约束；research 保存证据、候选与门槛；Git/PR 保存时间线。顶层只索引深层事实，不复制正文。 +- 已接受的需求、设计变化、调研结论、可执行 TODO、阻塞和状态必须在依赖工作继续前落到对应 Git 跟踪文件。阶段边界、分支/PR/agent 交接和压缩风险是自动检查点；恢复后先重读快照和 Git 状态。 - 非平凡变更先做一手资料调研，耐久结论才进入 `docs/research/`；大量原始资料不进入常驻 memory。 - 快速确定的约束由 tracked Git hook 和 CI 执行，判断型检查留给测试和评审。 - 每个重大 PR 都包含一次上下文卫生检查：更新新事实、删除旧事实、确认没有未跟踪项目文件。 + +上述“自动检查点”和分层归属是本仓库根据官方机制做出的工程约束，不是这些工具自动提供的跨工具同步能力。来源均于 2026-08-19 访问；Hermes Agent 来源为其官方仓库，Claude Code 与 Codex/OpenAI 来源为各自官方文档。