Back to Details

place-knowledges

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Place Knowledge

知识归置

Decide where each useful piece of knowledge should live so that the current system remains understandable after the change context is forgotten.
Treat knowledge placement as ownership, not documentation coverage. Each useful fact should have one authoritative home. Do not repeat the same knowledge across artifacts merely to make the change feel explained.
决定每一项有用知识应存放在何处，使当前系统在变更上下文被遗忘后仍能被理解。
将知识归置视为所有权问题，而不是文档覆盖问题。每一项有用事实都应有一个权威归属。不要仅仅为了让变更看起来已被充分解释，就在多个 artifact 中重复同一知识。

Core ownership rules

核心所有权规则

Use these as exclusive defaults:
  • Code owns How. Implementation expresses how the system works and enforces invariants. Do not restate implementation mechanics in comments or tests when they are already evident from the code.
  • Tests own What. Tests preserve observable behavior, boundaries, failures, recovery, and regression contracts. Prefer behavioral requirements over explanations of implementation structure.
  • Commit history owns Why. Commit messages preserve why this change was made, including non-obvious rationale and immediate compatibility consequences. They may contain enough what to identify the change, but should not become the sole home for stable current behavior or contracts.
  • Implementation comments own Why not. An implementation comment should exist only when a future maintainer could otherwise make an apparently reasonable but incorrect local change. Preserve the stable reason that a tempting simplification, refactor, API, algorithm, ordering, conversion, or alternative must not be used. Do not use comments to narrate what the code does, restate how it works, or preserve merely historical rejected alternatives.
If a knowledge item does not fit one of these homes, place it in the artifact whose reader or contract actually owns it. Documentation, schemas, configuration, migrations, examples, and decision records are first-class authorities when they define public usage, data shape, compatibility, or history.
将以下规则作为默认且互斥的归属原则：
  • 代码负责 How。 实现代码表达系统的工作方式并执行不变量。当实现机制已可从代码中清楚看出时，不要在注释或测试中重复说明。
  • 测试负责 What。 测试保留可观察行为、边界、失败、恢复以及回归 contract。优先表达行为要求，而不是对实现结构的解释。
  • Commit 历史负责 Why。 Commit message 保留进行此变更的原因，包括不明显的理由和直接产生的兼容性影响。它们可以包含足以识别变更的 What，但不应成为当前稳定行为或 contract 的唯一归属。
  • 实现注释负责 Why not。 只有当未来的维护者可能会做出看似合理但实际错误的局部修改时，才应存在实现注释。保留稳定的原因，说明为何不能采用某个看似简单的方案、重构、API、算法、顺序、转换方式或替代方案。不要用注释叙述代码做了什么、重复其工作方式，也不要仅仅保留历史上曾被否决的替代方案。
如果某项知识不适合放入上述任何归属，应将其放入其读者或 contract 真正拥有的 artifact。文档、schema、配置、迁移、示例和决策记录在定义公共用法、数据形态、兼容性或历史时，均属于一等权威来源。

Contract

Contract

  • Input: the authoritative current behavior or requirement, the relevant change or diff, and the artifacts that may need to preserve it.
  • Output: a concise placement plan identifying each knowledge item, its authoritative home, any justified projections, and the action required.
  • Side effects: none. This skill decides placement; the workflow that owns each artifact performs any resulting edit or repository operation.
  • Failure: if the current state, authority, or intended audience is ambiguous, inspect the relevant artifacts and ask or stop rather than guessing or duplicating information everywhere.
  • 输入： 权威的当前行为或要求、相关变更或 diff，以及可能需要保留该知识的 artifacts。
  • 输出： 一份简洁的归置计划，标明每项知识、其权威归属、任何有充分理由的 projection，以及所需操作。
  • 副作用： 无。此 skill 仅决定归置；由负责各项 artifact 的工作流执行后续编辑或 repository 操作。
  • 失败： 如果当前状态、权威归属或预期受众不明确，应检查相关 artifacts 并提出问题或停止，而不是猜测或到处重复信息。

Scope

范围

This skill answers where should this information live? It does not draft or edit the chosen artifact, summarize a commit, or execute a repository operation.
此 skill 回答 “这条信息应存放在哪里？” 它不会起草或编辑选定的 artifact、总结 commit，或执行 repository 操作。

Workflow

工作流

  1. Establish the current state from the source of truth and the relevant diff. Separate stable behavior, user-facing usage, local constraints, regression contracts, implementation detail, and historical rationale. For a correction, render from the resulting state rather than preserving rejected alternatives unless the artifact is explicitly history-sensitive or the rejected alternative remains a plausible future mistake that must be prevented.
  2. Find existing homes before creating or editing artifacts. Prefer one authoritative home for each fact; note a current artifact that should be updated or removed instead of creating a competing explanation.
  3. Classify each knowledge item:
    • Code: how the system implements behavior and enforces invariants.
    • Tests: what observable behavior, boundaries, failures, recovery, and regression contracts the system must preserve.
    • Implementation comments: why an otherwise reasonable local change or simplification must not be made. The constraint must be stable, non-obvious, and not inferable from the surrounding code.
    • Documentation or examples: current usage, public contracts, and user-facing or architectural guidance. API documentation comments and docstrings belong here and may describe behavior, inputs, outputs, and errors.
    • Schema, configuration, or migration: the authoritative data or compatibility contract for that concern.
    • Commit message: why this commit exists, plus only enough what to identify the change and its immediate compatibility consequences. It is history, not the sole home for stable behavior.
    • Decision record, changelog, or migration guide: rationale and before/after context that future readers explicitly need as history.
  4. Add a projection only when it enforces a distinct contract or serves a reader who cannot rely on the authoritative home. A projection is not justified merely because repeating the information would make an artifact easier to read. Derive it from the authoritative home, keep wording consistent, and omit it when the information is already obvious from the source, test, schema, or diff.
  5. Before adding an implementation comment, apply this check:
    If this comment were deleted, could a future maintainer reasonably make a locally sensible change that would violate a hidden constraint?
    If no, omit the comment. If yes, write only the constraint and why the tempting alternative is wrong; do not narrate the existing implementation.
  6. Produce the placement plan in this shape:
    KnowledgeAuthorityProjection or actionReason
    [fact or rationale][one artifact][none or distinct artifact][reader or contract served]
  7. Validate the plan before handing it off:
    • every necessary stable fact has exactly one authoritative home;
    • code carries implementation knowledge instead of explanatory comments;
    • tests state behavioral contracts rather than mirror implementation detail;
    • implementation comments contain only stable why not constraints, not code narration or historical residue;
    • no explanation exists only in a commit message when it must survive as current usage, behavior, or a contract;
    • duplicated knowledge exists only where another artifact enforces a distinct contract or serves a reader that cannot rely on the authority;
    • current-state artifacts contain no accidental correction residue;
    • commit-message input contains only commit-specific what/why;
    • unresolved ownership or audience decisions are surfaced instead of silently assigned.
Return the placement plan and any unresolved decision. Do not write prose or modify files as part of this skill.
  1. 根据事实来源（source of truth）和相关 diff 确认当前状态。区分稳定行为、面向用户的使用方式、局部约束、回归 contract、实现细节和历史原因。对于修正，应以变更后的状态为依据进行表述，而不是保留被否决的替代方案；除非该 artifact 明确关注历史，或被否决的替代方案仍可能成为未来看似合理的错误选择而必须加以防止。
  2. 在创建或编辑 artifacts 前，先找到现有归属。优先为每项事实确定一个权威归属；指出应更新或移除的现有 artifact，而不是创建相互竞争的解释。
  3. 对每项知识进行分类：
    • 代码： 系统实现行为并执行不变量的方式。
    • 测试： 系统必须保留的可观察行为、边界、失败、恢复和回归 contract。
    • 实现注释： 为何不能进行某个看似合理的局部修改或简化。该约束必须稳定、不明显，且无法从周边代码推断。
    • 文档或示例： 当前用法、公共 contract，以及面向用户或架构的指导。API 文档注释和 docstrings 属于此类，可以描述行为、输入、输出和错误。
    • Schema、配置或迁移： 特定关注点的数据或兼容性权威 contract。
    • Commit message： 此 commit 存在的原因，以及仅够识别变更和直接兼容性影响的那部分 What。它是历史信息，不应成为稳定行为的唯一归属。
    • 决策记录、changelog 或迁移指南： 未来读者明确需要作为历史了解的原因，以及变更前后的背景。
  4. 仅当 projection 可执行不同 contract，或服务于无法依赖权威归属的读者时，才添加 projection。仅仅因为重复信息会让某个 artifact 更容易阅读，不足以构成添加 projection 的理由。应从权威归属衍生 projection，保持措辞一致；如果信息从权威来源、测试、schema 或 diff 中已经显而易见，则省略。
  5. 添加实现注释前，先进行以下检查：
    如果删除此注释，未来的维护者是否可能做出一个局部上看似合理、却会违反隐藏约束的修改？
    如果不会，则省略该注释。如果会，则只写明约束以及看似有诱惑力的替代方案为何错误；不要叙述现有实现。
  6. 按以下格式生成归置计划：
    知识权威归属Projection 或操作原因
    [事实或理由][一个 artifact][无或不同的 artifact][所服务的读者或 contract]
  7. 移交前验证计划：
    • 每项必要的稳定事实都恰好有一个权威归属；
    • 代码承载实现知识，而不是解释性注释；
    • 测试陈述行为 contract，而不是镜像实现细节；
    • 实现注释只包含稳定的 Why not 约束，不包含代码叙述或历史残留；
    • 当某项信息必须作为当前用法、行为或 contract 长期保留时，不能只存在于 commit message 中；
    • 只有当另一个 artifact 执行不同 contract，或服务于无法依赖权威归属的读者时，重复的知识才存在；
    • 描述当前状态的 artifacts 中不包含因修正而意外残留的旧内容；
    • commit message 输入仅包含该 commit 特有的 What 和 Why；
    • 未解决的归属或受众决策会被明确指出，而不是被静默分配。
返回归置计划及任何未解决的决策。在此 skill 的执行过程中，不要撰写额外说明或修改文件。