# Zc Context Engineering

> 上下文工程

- Skill: `zmice/zc-context-engineering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmice/zc-context-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmice/zc-context-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zmice (https://skillmd.com/u/zmice)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zmice/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 项目上下文骨架