Context Management

上下文与指令管理 Skill

本 Skill 用于指导 LLM/Agent 在复杂项目中：

• 明确“指令 vs 信息”的区分
• 把长期记忆外化到文件（AGENTS.md / SESSION_NOTES.md）
• 在接受新指令时做冲突检测
• 控制上下文长度，避免无脑堆日志
• 提供可追踪、可审计的决策记录

1. 何时使用本 Skill

当满足以下任一条件时，应主动启用本 Skill 的行为规范：

• 任务跨越多轮调用或多个 Agent，需要「记住前情」；
• 需要在一个仓库/项目内固化规则与工作流；
• 用户或其他 Agent 提到：
  • AGENTS.md、SESSION_NOTES.md、会话笔记、交接文档 等；
  • “帮我管理上下文 / 指令 / 规则”；
• 上下文变长，模型开始显得遗忘、反复、指令不一致；
• 存在不同人（或 Agent）反复参与同一项目，容易跑偏。

如果当前任务只是一次性、几句话就能完成的小活，可以不主动使用本 Skill（除非用户明确要求）。

2. 核心理念（Skill 的设计哲学）

1. 指令与信息分离

   • 指令（Instructions）：
     • 规定“要怎么做事”的元规则；
     • 如风格偏好、安全约束、不能做的事、阶段性侧重点。
   • 信息（Facts/State）：
     • 描述“世界/项目当前是什么样”的事实；
     • 如架构设计、实现细节、TODO 列表、已知 bug 记录等。

   本 Skill 要求：

   • 指令写在 AGENTS.md + SESSION_NOTES.md 的「指令与约束」部分；
   • 项目状态与事实写在「重要背景」「近期工作记录」「TODO」。

2. 渐进式信息披露（Progressive Disclosure）

   • 不要一股脑把所有历史对话、全部文档塞进上下文；
   • 优先：
     1. 定位：找到相关文件和章节；
     2. 概括：在内部思考中做小结；
     3. 引用：对用户使用“指向 + 摘要”的方式回答；
   • 只有在确实需要时，才展开详细内容。

3. 文件系统即外部记忆

   • 把稳定的知识放在文件里，而不是只放在一段长聊天中；
   • Skill 的指令短小清晰，把复杂细节拆到：
     • AGENTS.md：Agent 行为准则；
     • SESSION_NOTES.md：项目当前状态与会话笔记；
     • 其他专门文档（如 docs/xxx.md）；
   • 这样做有三个目的：
     • 减少 token 压力；
     • 提供可版本控制的“记忆”；
     • 让多 Agent / 多人都能共享同一套认知。

4. 明确、可审计的决策与指令变更

   • 每次指令变化、冲突解决、重大架构决策
     必须以“可追踪文字”形式写入文档，而不是只说在对话里；
   • 方便日后复盘：
     “当时为什么这么决定？谁改的指令？覆盖了什么旧规则？”

5. 将复杂任务拆分为阶段并外化成计划文档

• 对于复杂/跨多轮的工作，建议使用 IMPLEMENTATION_PLAN.md：
  • 按 3–5 个 Stage 拆分目标；
  • 为每个 Stage 约定可验证的成功标准与测试；
  • 在推进过程中更新 Stage 状态；
  • 完成后可删除或归档该计划文件。
• 这样做可以让多个 Agent / 人类在多轮对话中保持同一认知。

3. 入口流程：启动本 Skill 时你要做的事

当本 Skill 被触发时，Agent 应该遵循以下步骤：

1. 检查并读取关键文档

   • 尝试读取根目录的：
     • AGENTS.md（如果不存在，可提示用户用模板新建）；
   • 尝试读取当前项目/代码仓内的：
     • codex/SESSION_NOTES.md 或类似约定路径；
     • 如果不存在，可使用 SESSION_NOTES.template.md 作为起点。

2. 在内部整理出三类列表

   （可在你的“隐藏思考”中完成，不必全部回显给用户）：

   • 指令类（来自 AGENTS + SESSION_NOTES：指令与约束）
     • 长期通用指令
     • 当前阶段指令
     • 临时/一次性指令
   • 事实类（来自 SESSION_NOTES：背景、决策、近期工作等）
   • 任务类（来自 TODO / Next steps + 用户最新请求）

3. 解析用户本轮请求

   • 把用户最新消息拆成：
     • 新增指令？（例如“之后都用中文回答”）
     • 本轮任务？（例如“帮我重构 X 文件”）
     • 对已有指令的修订？（例如“之前说不要改 DB，现在可以改了”）

4. 对新指令进行“冲突检测”

   • 将本轮新指令与已有指令列表比对；
   • 如果存在明显冲突或覆盖关系：
     • 在回复中明确指出冲突点；
     • 停止执行与冲突相关的操作；
     • 请用户选择：
       • 覆盖旧指令；
       • 作为特殊例外（附范围说明）；
       • 或维持旧指令、忽略新请求中某部分。
   • 只有在用户明确确认后，才更新指令列表并执行工作。

5. 形成本轮的“工作计划”

   • 结合：
     • 已确认的指令集合；
     • 当前项目事实；
     • 用户本轮具体任务；
   • 在内部列出 3–7 个步骤的小计划后再开始动手。

4. 执行阶段：在任务中如何使用本 Skill

在具体执行工作（写代码、改文档、分析数据等）时，应遵循：

1. 优先查文档后再推理

   • 对于：
     • 项目约定；
     • 目录结构；
     • 已存在设计决策；
   • 不要直接瞎猜，应先在文件系统中查找相关信息：
     • AGENTS.md
     • SESSION_NOTES.md
     • docs/ 目录
     • 其他明显相关文件（如 DESIGN.md、ARCHITECTURE.md）。

2. 小步修改 + 明确说明

   • 每次只改少量相关文件；
   • 在对话中简单说明：
     • 改了哪些文件；
     • 主要改动点；
     • 影响范围；
   • 如果能运行测试或检查命令，也应说明命令和结果。

3. 控制上下文长度

   • 不要在对话中无脑贴巨大文件原文；
   • 优先：
     • 用「文件路径 + 小节标题 + 摘要」的方式指代；
     • 在需要用户确认时，可以粘贴必要片段（非整篇）。

4. 尊重指令层级与来源

   • 默认层级排序（从高到低）：
     1. 系统/平台级指令（不在此 Skill 内，但你应遵守）；
     2. AGENTS.md 中的长期指令；
     3. SESSION_NOTES 中明确记录的阶段性指令；
     4. 本轮用户的临时指令；
     5. 你自己的常识与默认偏好。
   • 如下层指令与上层冲突，以上层为准，并向用户说明。

5. 遇到卡壳时的处理方式

• 对同一思路连续尝试的次数不宜超过 3 次：
  • 如果发现自己在“重复同一种做法但一直失败”，应主动停下来；
• 停止继续 brute force，改为：
  • 写下尝试过的方案和错误现象；
  • 从代码库中找 2–3 个类似实现做对比；
  • 重新评估抽象层级和拆分方式；
  • 必要时向用户汇报当前困境并请求决策；
• 执行新的方案前，可在 SESSION_NOTES 中简要记录“思路切换”的原因。