Back to Details

to-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

To Docs

转化为文档

Turn recent work into durable guidance without treating the session as a changelog.
将近期工作转化为持久化指导方案，而非将本次会话当作变更日志。

Phase 1: Propose

第一阶段：提案

Do not edit project documentation during this phase.
  1. Read the repository instructions and the existing documents that could own the guidance. Distinguish committed guidance from uncommitted documentation drafts; do not treat a draft as approved policy merely because it exists in the worktree.
  2. Use the conversation or user-specified work as the authoritative scope. Reconstruct its material decisions from the discussion, relevant code, and focused diffs. Include implicit decisions revealed by rejected alternatives or later corrections. Treat unrelated dirty-worktree changes as out of scope, and use diffs as evidence rather than as a backlog of decisions to document.
  3. Evaluate each decision instead of merely classifying it. Ask:
    • Would this guide work on another resource or page?
    • Does it express an intended invariant rather than describe the current implementation?
    • Would a future coding agent make a materially better choice by knowing it?
    • Can its scope, exceptions, and failure cases be stated clearly?
    • Is it supported by repeated use or strong design reasoning rather than one accidental example?
    • Is it already documented adequately?
    • Does it contradict existing guidance, lint rules, tests, or shared modules?
  4. Test candidate rules against counterexamples. Reject or narrow rules that become semantically wrong outside the original case.
  5. Classify each material decision as one of:
    • Document: durable, general guidance.
    • Refine existing guidance: already present but incomplete, misleading, or contradicted by the new decision.
    • Already covered: requires no documentation change.
    • Keep local: resource, route, copy, naming, or implementation detail.
    • Defer: plausible pattern without enough evidence to make it a project rule.
  6. Present only the meaningful results. For every proposed documentation change include:
    • the generalized rule;
    • why it deserves project-wide status;
    • its scope and exceptions;
    • the document that should own it;
    • contradictions or related enforcement that must be updated with it.
  7. Explicitly list important decisions rejected from project documentation and explain why.
  8. End by requesting approval of the proposal. Do not edit documentation until the user explicitly approves it.
If the decision history is unavailable or the requested scope cannot be separated reliably from unrelated work, state that limitation and ask for the missing fixed point or decision context instead of inferring policy from the whole worktree.
Prefer modifying an existing authoritative document over creating a new one. Avoid duplicating the same rule across documents; put the complete rule in one owner and use short cross-references elsewhere.
本阶段请勿编辑项目文档。
  1. 阅读repository说明文档以及可能承载该指导方案的现有文档。区分已确认的指导方案与未提交的文档草稿；不要仅仅因为草稿存在于worktree中就将其视为已批准的政策。
  2. 以对话内容或用户指定的工作作为权威范围。从讨论内容、相关代码和聚焦的diffs中重构关键决策。包括被否决的替代方案或后续修正所揭示的隐含决策。将无关的worktree变更视为超出范围，并将diffs作为证据，而非待记录决策的待办清单。
  3. 评估每个决策，而非仅对其进行分类。请思考：
    • 该指导方案是否适用于其他资源或页面？
    • 它是否表达了预期的不变性，而非描述当前的实现？
    • 未来的coding agent了解它后，能否做出更优的选择？
    • 能否清晰说明其适用范围、例外情况和失败场景？
    • 它是否得到反复实践或强有力的设计推理支持，而非仅仅是偶然案例？
    • 是否已拥有足够充分的文档记录？
    • 它是否与现有指导方案、lint规则、测试或共享模块相矛盾？
  4. 用反例测试候选规则。若规则在原案例之外出现语义错误，则予以否决或缩小其适用范围。
  5. 将每个关键决策归类为以下类型之一：
    • 记录：持久化的通用指导方案。
    • 完善现有指导方案：已有相关内容但不完整、易误导，或与新决策相矛盾。
    • 已覆盖：无需修改文档。
    • 仅本地保留：资源、路径、文案、命名或实现细节。
    • 暂缓：看似可行但缺乏足够证据成为项目规则的模式。
  6. 仅呈现有意义的结果。对于每个拟议的文档变更，需包含：
    • 通用化规则；
    • 其值得成为项目级规范的原因；
    • 适用范围与例外情况；
    • 应承载该规则的文档；
    • 必须同步更新的矛盾内容或相关执行机制。
  7. 明确列出未纳入项目文档的重要决策，并说明原因。
  8. 最后请求批准提案。在用户明确批准前，请勿编辑文档。
若决策历史不可用，或无法将请求范围与无关工作可靠区分，请说明该限制，并请求提供缺失的固定参考点或决策背景，而非从整个worktree中推断政策。
优先修改现有权威文档，而非创建新文档。避免在多个文档中重复相同规则；将完整规则放在一个主文档中，其他地方使用简短交叉引用。

Phase 2: Apply after approval

第二阶段：批准后执行

After explicit approval:
  1. Use /writing-for-agents and apply its writing discipline throughout this phase. If it is unavailable, stop and ask the user to install it with 
    npx skills@latest add mattpocock/skills --skill writing-for-agents
    .
  2. Re-read every affected document before editing it.
  3. Apply only the approved rules and preserve the repository's terminology and language requirements.
  4. Reconcile the full documentation set: remove obsolete guidance, resolve contradictions, and update cross-references.
  5. Update enforcement when the documented policy is mechanically checked, such as lint configuration, shared modules, or tests. Do not leave documentation and enforcement disagreeing.
  6. Keep resource-specific examples illustrative; do not turn their names, routes, fields, or query parameters into universal policy.
  7. Run checks proportional to the changed documentation and enforcement. Report checks not run.
  8. Summarize the durable rules written, their owning documents, and any approved follow-up work still needed in code.
获得明确批准后：
  1. 使用/writing-for-agents，并在本阶段全程遵循其写作规范。若该技能不可用，请停止操作并要求用户通过
    npx skills@latest add mattpocock/skills --skill writing-for-agents
    安装。
  2. 编辑前重新阅读所有受影响的文档。
  3. 仅应用已批准的规则，并保留repository的术语和语言要求。
  4. 协调整个文档集：移除过时的指导方案，解决矛盾，更新交叉引用。
  5. 当文档化政策可通过机械方式检查时（如lint配置、共享模块或测试），同步更新执行机制。请勿让文档与执行机制不一致。
  6. 保留特定资源的示例作为说明；不要将其名称、路径、字段或查询参数转化为通用政策。
  7. 根据文档和执行机制的变更程度运行相应检查。报告未执行的检查。
  8. 总结已编写的持久化规则、其承载文档，以及代码中仍需完成的已批准后续工作。

Quality bar

质量标准

A useful guideline tells a future agent what to choose, why, where it applies, and when not to apply it. Reject rules that only restate the final code, encode personal preference without a project invariant, or prescribe a mechanism where a semantic rule would age better.
实用的指南应告知未来的agent要选择什么、为什么选择、适用场景以及不适用场景。否决那些仅重述最终代码、将个人偏好编码为项目规则（而非基于项目不变性），或在应使用语义规则时指定具体实现机制的规则。