Best Practices

These practices come from teams using Context to build knowledge for large engineering organizations. Most of them are about one thing: correct course early, while it is cheap.

Talk first, then start

After initializing the Context knowledge workspace, have a free conversation before any production. Explain what the knowledge should cover, where it comes from — document links, repository addresses, the modules you care about — and what form you expect. The Agent researches and asks back until it can write a work-start report: the confirmed configuration and scope, the planned content, and the expected package or site layout. See Start Reports.

Production then takes time — on average about one minute per task. The Agent keeps reporting progress and the total number of tasks, and you can ask for a local preview at any point. After publication, check the package and other outputs; the Agent commits the workspace to Git to close the production.

Preview early, correct with examples

On a large task, open the work-start report and the changed pages as soon as they are available. If something is off, ask for a revision and be specific: show the wording you want, give a counterexample, describe the style. The earlier you correct, the better the final quality.

Three questions for every review

The review report decides the scope and quality of what gets approved. Read it with three questions:

1. Does the structure — topics, directories, documents — match what you expected?
2. Does the content — the intent of each article, its style — match what you expected?
3. Is anything relevant still missing from the scope, or included that should be left out?

See Reading Review Reports.

Reorganize once the knowledge grows

First-version titles tend to be abstract, and directory names and structure are rarely ideal. Once the knowledge has grown, ask the Agent to research the approved knowledge again and propose a more readable, intuitive directory and article structure — it does this better now than it could during planning. Revise, then observe for another round. Revising costs far less than producing again and suits fine-tuning of both structure and content. See Reorganizing at Scale.

When documents lag behind code

Production cross-checks sources, and documents lagging behind code is normal. By default the Agent revises the knowledge to match the code. To fix the upstream documents as well, add a rule at the start of the task or in the workspace AGENTS.md:

When a revision is caused by a document lagging behind code, record it in
update-remote/<date>-<topic>.md with the context, the judgment and a suggested fix.
After the task, work through update-remote: find each upstream document and
revise it, or give a concise suggested fix for the user to decide.

Upstream documents then stay current and the knowledge does not drift away from them. See Writing Back Upstream.

Split very large work into batches

A very large task goes through planning first, with at most about 30 to 50 documents per batch. Each batch is produced, published, recorded in the plan file (PLAN-*.md) and committed before the next one starts. See Planning a Large Project.

最佳实践

这些实践来自使用 Context 为大型研发组织建设知识的团队。它们大多围绕一件事：尽早纠偏，趁代价还小的时候。

先对话，再开工

初始化 Context 知识工作区后，先自由对话，不要急于开始生产。说明知识应覆盖什么、来自哪里（文档链接、仓库地址、你关心的模块），以及你期望的形式。Agent 会调研并反问，直到能写出一份开工报告：已确认的配置和范围、计划产出的内容，以及预期的知识包或站点结构。参见开工报告。

之后的生产需要一些时间，平均每个任务约一分钟。Agent 会持续汇报进度和任务总数，你随时可以要求本地预览。发布后，检查知识包和其他产物；Agent 会把知识工作区提交到 Git，结束本次生产。

尽早预览，用示例纠偏

在大型任务中，开工报告和有变更的页面一出来就打开看。如果有不对的地方，要求修订，并且说得具体：给出你想要的措辞、举一个反例、描述你要的风格。纠偏越早，最终质量越好。

每次审核问三个问题

审核报告决定了哪些内容会被批准，以及它们的质量。阅读时问自己三个问题：

1. 结构（主题、目录、文档）是否符合预期？
2. 内容（每篇文章的意图、风格）是否符合预期？
3. 是否还有相关内容遗漏在范围之外，或者纳入了本该排除的内容？

参见阅读审核报告。

知识变多后重新组织

第一版的标题往往偏抽象，目录名称和结构也很少一开始就理想。知识积累起来后，让 Agent 重新调研已批准的知识，提出更易读、更直观的目录和文章结构；此时它会比规划阶段做得更好。修订之后，再观察一轮。修订的成本远低于重新生产，适合对结构和内容做微调。参见大规模重新组织。

文档落后于代码时

生产过程会交叉核对来源，文档落后于代码是常态。默认情况下，Agent 会按代码修订知识。如果你还想修正上游文档，可以在任务开始时或在知识工作区的 AGENTS.md 中加一条规则：

When a revision is caused by a document lagging behind code, record it in
update-remote/<date>-<topic>.md with the context, the judgment and a suggested fix.
After the task, work through update-remote: find each upstream document and
revise it, or give a concise suggested fix for the user to decide.

这样上游文档能保持最新，知识也不会与它们逐渐脱节。参见回写上游。

超大任务分批进行

超大任务要先经过规划，每个批次最多约 30 到 50 篇文档。每个批次都要完成生产、发布、记录到计划文件（PLAN-*.md）并提交，然后再开始下一批。参见规划大型项目。