Zc Context Engineering

上下文工程

这是 command:start 判型后进入的专项 skill：当任务核心不是“做什么”，而是“如何把正确上下文装载给接下来的阶段”，进入这里。

何时使用

• 开始新的编码会话或新子任务时
• 输出质量下降，开始出现幻觉、忽略约定或跑偏
• 任务切换导致上下文混杂时
• 需要为代理准备最小但足够的输入材料时

方法原则

• 复杂任务先校准目标、边界和验证方式，再装载上下文
• 最小充分上下文优先于“大而全”材料堆叠
• 上下文装载要服务当前任务，不为可能发生的旁支需求提前铺料
• 一旦任务阶段变化，就主动压缩和重建上下文，避免 drift
• skill 按需加载优先于常驻加载；常驻文件只放稳定项目约定和路由规则
• 用户级配置、跨项目路由、跨会话记忆或跨机器同步都属于持久化行为，必须先说明影响并取得明确授权

输入前提

• 已知道当前任务真正需要哪些信息
• 愿意主动裁剪无关上下文
• 接受规则文件、规格、源码、错误输出有不同优先级

执行步骤

1. 先校准：明确目标、非目标、风险点和需要的验证证据
2. 先装载稳定规则：规则文件、长期约定、关键边界
3. 再装载任务级上下文：规格片段、相关源码、测试、错误输出
4. 控制上下文体积，只保留当前任务需要的信息
5. 任务切换或阶段推进时主动压缩总结，清理旧上下文
6. 发现上下文冲突、缺口或陈旧信息时，显式暴露而不是猜测
7. 区分上下文载体：
   • AGENTS.md / CLAUDE.md / GEMINI.md：长期规则、项目边界、稳定路由
   • skill 文件：阶段性工作流，按需加载
   • references / checklists：需要深入验证时再加载
   • 用户级配置或记忆：只在明确授权后写入

Codex 项目可以用 context-init 初始化 .codex/context/ 索引。该命令只维护项目级上下文骨架，不写用户级配置，不替代当前任务的源码阅读。

Context Steward Sidecar

当上下文维护会打断主流程时，优先把它拆给 agent:context-steward：

• 主线程继续处理当前需求，保留 controller / integrator 角色。
• context steward 默认 scoped_write，负责审计并维护 .codex/context/**、AGENTS.md managed block、package scripts、README 和模块入口的一致性。
• context steward 先运行 zc context init --plan --json，候选变更只涉及自有边界时继续执行 zc context init --write --json 或等价最小编辑。
• 写入只限 .codex/context/** 和 AGENTS.md 的 zc-context:init managed block；涉及用户手写规则、业务源码、用户级配置或跨项目记忆时必须降级 fan-in。
• 如果上下文维护和主任务都要改 AGENTS.md，先停在 fan-in，由主线程合并，不让两个 worker 同时写。

成功标准

• 开始执行前，代理已经知道目标、边界和验证方式
• 代理看到的是当前任务需要的最小充分上下文
• 规则、规格、源码和错误信息的层级清晰
• 上下文切换不会把旧问题带入新任务
• 遇到冲突时能清楚指出需要人类决策的点
• 不会因为上下文膨胀而偏离当前任务
• 没有为了“方便”把所有 skill、所有上游文档或所有历史记忆一次性塞入当前会话
• 任何越过项目上下文自有边界的持久化写入都有明确授权、可解释影响和回滚路径
• 上下文维护没有挤占主流程；sidecar 报告清楚说明 stale / missing / conflict / updated、写入证据和 fan-in 结果。

相关原则

• 复杂任务谨慎优先于求快
• 少而准，比多而杂更有效
• 目标导向决定装载顺序
• 外科式修改也适用于上下文，只带入要改的那一小块
• 规格和规则优先于猜测
• 压缩上下文是持续动作，不是最后补救
• 上游能力先变成治理记录，再决定是否成为常驻规则或平台能力

回到主流程

• 上下文已校准完成：回到后续真正要执行的阶段或专项入口
• 需求仍模糊：回到 spec-driven-development
• 任务已经明确、准备实现：回到 incremental-implementation
• 会话健康恶化明显：结合 context-budget-audit
• 项目缺少稳定上下文索引：先运行 context-init 生成 Codex 项目上下文骨架