Back to Details

ds-spec-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DS Spec Loop

DS 规范循环

Treat the spec as a repository-wide authority system, not one planning document. Keep six surfaces coherent:
  • repository instructions and architecture invariants;
  • current-state documentation and public contracts;
  • lifecycle-managed decision notes;
  • source, types, package topology, configuration, and generated artifacts;
  • executable evidence such as unit, integration, replay, snapshot, and end-to-end tests;
  • mechanical gates for facts a program can decide.
Preserve the user's requested boundary. 
specify only
, 
verify only
, 
review
, 
implement
, and 
simplify
are different assignments. Do not silently turn one into another.
将规范视为覆盖整个代码仓库的权威体系，而非单一的规划文档。确保以下六个层面保持一致：
  • 仓库说明与架构约束；
  • 当前状态文档与公开契约；
  • 全生命周期管理的决策记录；
  • 源代码、类型定义、包拓扑结构、配置文件与生成产物；
  • 可执行验证依据，如单元测试、集成测试、重放测试、快照测试与端到端测试；
  • 由程序判定事实的机械性校验门控。
严格遵循用户指定的边界。
仅编写规范
、
仅验证
、
评审
、
实现
和
简化优化
是不同的任务，不得擅自将一种任务转换为另一种。

Load the relevant reference

加载相关参考文档

  • Read system-of-authority.md before changing a repository's spec system or deciding which artifact owns a fact.
  • Read agent-note-lifecycle.md whenever creating, moving, superseding, rejecting, or archiving a decision note.
  • Read decision-classes.md for the class-specific content and evidence expected from feature, bug-fix, simplification, architecture, process, or testing decisions.
  • Read acceptance-and-evidence.md before writing acceptance criteria, implementing a spec, or verifying completion.
  • Read simplification.md for removal, consolidation, replacement, or “clean up” work.
  • Read documentation-discipline.md when adding or restructuring instructions, current-state docs, references, generated docs, or archive policy.
  • Read adoption.md when installing this method into a repository that has no equivalent conventions.
  • Use templates.md when authoring repository artifacts. Adapt names and paths to existing repository conventions.
  • 在修改仓库的规范体系或确定哪个工件负责记录某项事实前，请阅读system-of-authority.md；
  • 在创建、迁移、替代、拒绝或归档决策记录时，请阅读agent-note-lifecycle.md；
  • 如需了解功能开发、Bug修复、简化优化、架构设计、流程改进或测试决策所需的特定类别内容与验证依据，请阅读decision-classes.md；
  • 在编写验收标准、实现规范或验证完成情况前，请阅读acceptance-and-evidence.md；
  • 如需进行代码移除、合并、替换或“清理”工作，请阅读simplification.md；
  • 在添加或重构说明文档、当前状态文档、参考资料、生成文档或归档策略时，请阅读documentation-discipline.md；
  • 在将此方法引入无等效约定的仓库时，请阅读adoption.md；
  • 在编写仓库工件时，请使用templates.md。可根据现有仓库约定调整名称与路径。

Reconstruct repository authority first

先重构仓库的权威体系

  1. Read the root instructions, then every more-specific instruction file governing the target subtree.
  2. Map the relevant current-state documents, public types/contracts, source entry points, assembly/composition path, tests, generated outputs, and gates.
  3. Search active proposed, implemented, and rejected decision records before creating one. Find the note that already owns the decision; update it instead of duplicating it.
  4. Treat archived records and Git history as historical evidence, not present authority.
  5. Inspect history when the current tree cannot explain intent, rejected alternatives, a first-proposed date, or a suspected drift.
  6. State unresolved contradictions before building on them. Prefer direct repository evidence over issue prose or stale plans.
Do not begin from a preferred implementation. First write a problem statement that remains true if the preferred solution is removed.
  1. 阅读根目录说明文档，然后阅读所有管辖目标子树的更具体的说明文件；
  2. 梳理相关的当前状态文档、公开类型/契约、源代码入口、组装/组合路径、测试用例、生成输出与校验门控；
  3. 在创建新的决策记录前，先搜索已有的提议中、已实现和已拒绝的决策记录。找到已负责该决策的记录，对其进行更新而非重复创建；
  4. 将归档记录与Git历史视为历史依据，而非当前权威；
  5. 当当前代码树无法解释意图、已被否决的替代方案、首次提议日期或疑似不一致时，检查历史记录；
  6. 在基于未解决的矛盾进行开发前，先明确说明这些矛盾。优先采用仓库中的直接证据，而非议题描述或过时的规划。
不要从偏好的实现方案开始。首先编写一个即使移除偏好解决方案仍成立的问题陈述。

Decide whether the change needs an Agent Note

判断变更是否需要创建Agent Note

Create or update a note in the same change whenever work alters behavior, architecture, a cross-file or cross-package contract, tooling/process, test strategy, durable/on-disk/wire/configuration format, or a decision maintainers may revisit.
Exempt only purely mechanical or local edits with no change to behavior, contract, structure, process, test strategy, or rationale. Do not use effort, diff size, or file count as the discriminator.
Classify the owning decision as exactly one of:
  • feature
    : new user- or model-facing capability;
  • bug-fix
    : defect correction or postmortem gap closure;
  • simplification
    : removal of code, behavior, or surface area without adding a capability;
  • architecture
    : structural decision about shipped source and runtime boundaries;
  • process
    : tooling, policy, or workflow around the code;
  • testing
    : test infrastructure or test strategy.
Use the host repository's established names if it already has an equivalent taxonomy. Otherwise follow adoption.md.
After classifying, apply the class-specific investigation and evidence requirements in decision-classes.md. Classification is not only a folder name; it identifies the durable decision and the most likely failure surfaces.
当工作涉及改变行为、架构、跨文件或跨包契约、工具/流程、测试策略、持久化/磁盘/网络/配置格式，或涉及维护者可能重新审视的决策时，请在同一次变更中创建或更新记录。
仅豁免那些不改变行为、契约、结构、流程、测试策略或决策依据的纯机械性或本地编辑。不得将工作量、差异大小或文件数量作为判断标准。
将所属决策精确归类为以下类别之一：
  • feature
    ：面向用户或模型的新功能；
  • bug-fix
    ：缺陷修复或事后漏洞弥补；
  • simplification
    ：移除代码、行为或功能面，不新增任何能力；
  • architecture
    ：关于已发布源代码与运行时边界的结构性决策；
  • process
    ：围绕代码的工具、政策或工作流；
  • testing
    ：测试基础设施或测试策略。
如果宿主仓库已有等效的分类体系，请使用其既定名称。否则遵循adoption.md中的约定。
分类完成后，应用decision-classes.md中针对该类别的调查与验证依据要求。分类不仅是文件夹名称，它还标识了持久化决策以及最可能出现故障的层面。

Establish the owning decision

确立所属决策

For substantial future work, create or repair a proposed note before implementation. Record:
  • a solution-independent problem;
  • the proposed decision and affected ownership boundaries;
  • genuine alternatives and why they lose;
  • observable acceptance criteria;
  • risks, trade-offs, and intentionally surrendered capability.
For a decision already shipped in the same small change, an implemented note may be created directly. Do not mislabel partial work as implemented.
Keep one owning note per decision. A note may contain bespoke technical sections—topology, protocol, schema, invariants, migration—but the lifecycle skeleton remains intact. Do not invent fake alternatives to satisfy a heading; investigate the record or say what evidence is unavailable.
对于重大的未来工作，请在实现前创建或完善提议记录。记录内容包括：
  • 独立于解决方案的问题描述；
  • 提议的决策及受影响的所有权边界；
  • 真实的替代方案及其被否决的原因；
  • 可观测的验收标准；
  • 风险、权衡取舍及主动放弃的能力。
对于已在同一次小型变更中完成的决策，可直接创建已实现的记录。不得将部分工作错误标记为已实现。
每个决策对应一条所属记录。记录可包含定制化的技术章节——如拓扑结构、协议、schema、约束、迁移——但生命周期框架需保持完整。不得为了满足标题要求而虚构替代方案；若无法找到相关记录，请说明缺失的依据。

Bind acceptance to falsifying evidence

将验收标准与可证伪依据绑定

For every acceptance statement, identify:
  1. the observable behavior or absence that would make it true;
  2. the layer where it can fail;
  3. the direct evidence that can falsify it;
  4. the exact command, inspection, or runtime path used to obtain that evidence.
Match evidence to the failure surface:
  • local logic and invariants → unit tests;
  • provider/loader/package composition → integration or composition tests;
  • persistence, recovery, or event reconstruction → replay/resume tests;
  • model- or user-visible behavior → runnable example plus stable snapshot;
  • external service behavior → real end-to-end test when access exists, otherwise an explicit unverified boundary;
  • deletion → negative search, absent path/registration/manifest/catalog/reference, and preserved replacement behavior;
  • documentation or generated-reference promises → repository-native sync checks;
  • architectural dependency direction → manifest/import/topology checks.
Static source inspection is evidence about source, not proof of runtime behavior. A passing format gate is evidence about encoded format rules, not semantic agreement between spec and implementation.
对于每条验收陈述，需明确：
  1. 使其成立的可观测行为或状态缺失；
  2. 可能出现故障的层面；
  3. 可证伪该陈述的直接依据；
  4. 获取该依据所使用的精确命令、检查方式或运行时路径。
依据需与故障层面匹配：
  • 本地逻辑与约束 → 单元测试；
  • 提供者/加载器/包组合 → 集成测试或组合测试；
  • 持久化、恢复或事件重构 → 重放/恢复测试；
  • 模型或用户可见行为 → 可运行示例加稳定快照；
  • 外部服务行为 → 若可访问则进行真实端到端测试，否则明确标记为未验证边界；
  • 删除操作 → 反向搜索、确认路径/注册/清单/目录/引用已移除，并确保替代行为正常；
  • 文档或生成参考的承诺 → 仓库原生的同步检查；
  • 架构依赖方向 → 清单/导入/拓扑结构检查。
静态源代码检查是关于源代码的依据，而非运行时行为的证明。格式校验通过仅能证明符合编码格式规则，不能证明规范与实现之间的语义一致。

Change the complete assembled path

修改完整的组装路径

Implement through the repository's actual composition path, not only a leaf module. Trace definition, provider, registration/loader, consumer, persistence, and UI/model exposure where they exist.
In the same change, update every authority surface whose fact changed:
  • source and public types/contracts;
  • relevant tests, fixtures, snapshots, and generated outputs;
  • current-state architecture or package documentation;
  • the owning decision note;
  • repository instructions or gates when the durable workflow itself changed.
Keep the patch scoped to the decision. Record unrelated discoveries instead of folding opportunistic refactors into the change.
需通过仓库实际的组合路径进行实现，而非仅修改叶子模块。追踪定义、提供者、注册/加载器、消费者、持久化以及UI/模型暴露（若存在）的全路径。
在同一次变更中，更新所有事实发生变化的权威层面：
  • 源代码与公开类型/契约；
  • 相关测试用例、测试夹具、快照与生成输出；
  • 当前状态的架构或包文档；
  • 所属决策记录；
  • 当持久化工作流本身发生变化时，更新仓库说明或校验门控。
保持变更范围与决策一致。对于无关的发现，仅进行记录，不得将机会性重构混入本次变更。

Review against the real consumer

针对真实消费者进行评审

Before claiming completion:
  1. Re-read the user request and owning note without looking at the implementation first.
  2. Check each acceptance criterion against direct evidence.
  3. Trace at least one real assembled execution path for user- or model-visible behavior.
  4. Check negative guarantees: what must no longer exist, happen, or be reachable.
  5. Review from the caller, model, user, and future maintainer perspective—not only the implementing module.
  6. Run the narrow relevant checks locally; leave unrelated full matrices to the repository's established CI unless the user requests them.
  7. Report commands actually run, meaningful outputs, skipped checks, and remaining uncertainty. Reserve “passed” for an executed check; describe manual source/doc comparison as “inspected” with exact paths. Never translate “not run” into “passed.”
在声明完成前：
  1. 先重新阅读用户请求与所属记录，不要先看实现方案；
  2. 对照直接依据检查每条验收标准；
  3. 至少追踪一条真实的组装执行路径，验证用户或模型可见的行为；
  4. 检查负面保证：哪些内容必须不再存在、发生或可访问；
  5. 从调用者、模型、用户及未来维护者的角度进行评审——而非仅从实现模块的角度；
  6. 本地运行相关的窄范围检查；除非用户要求，否则将无关的全量矩阵检查留给仓库既定的CI流程；
  7. 报告实际运行的命令、有意义的输出、跳过的检查以及剩余的不确定性。仅对已执行的检查使用“通过”描述；将手动的源代码/文档对比描述为“已检查”并注明精确路径。绝不能将“未运行”表述为“通过”。

Converge lifecycle and current truth

使生命周期与当前事实保持一致

After the implementation and evidence agree, move 
proposed
to 
implemented
and rewrite it as present truth:
  • change 
    Proposal
    to 
    Decision
    ;
  • replace future plans with what actually shipped;
  • fold acceptance and risks into present-tense consequences and testing/verification;
  • update paths, package names, defaults, contracts, and other factual locations;
  • preserve why the decision won and what it gave up.
If the proposal is declined, move it to 
rejected
, put the concise reason in the status, and preserve the evaluated proposal and alternatives. If a decision changes, supersede it with a new cross-linked note; do not edit the old note into its opposite.
Archive only implemented decisions whose rationale is unlikely to guide future work. Keep active any note that still owns an alternative, boundary, negative guarantee, durable or wire semantic, security rule, reintroduction condition, or named coverage gap. Never use archived text as current authority.
Finish by checking that current-state docs describe current behavior, active notes describe current decisions, tests pin observable promises, and no proposed text falsely reads as completed.
在实现方案与验证依据一致后，将
proposed
（提议）状态改为
implemented
（已实现），并将其改写为当前事实：
  • 将“Proposal”改为“Decision”；
  • 用实际交付的内容替换未来计划；
  • 将验收标准与风险融入现在时态的结果与测试/验证内容；
  • 更新路径、包名称、默认值、契约及其他事实性信息；
  • 保留该决策胜出的原因及主动放弃的内容。
若提案被否决，将其移至
rejected
（已拒绝）状态，在状态中注明简洁原因，并保留已评估的提案与替代方案。若决策发生变更，用新的交叉链接记录替代旧记录；不得将旧记录修改为相反内容。
仅对其依据不太可能指导未来工作的已实现决策进行归档。对于仍涉及替代方案、边界、负面保证、持久化或网络语义、安全规则、重新引入条件或命名覆盖缺口的记录，需保持活跃状态。绝不能将归档文本作为当前权威。
最后检查：当前状态文档是否描述当前行为，活跃记录是否描述当前决策，测试是否固定可观测的承诺，是否存在将提议文本错误表述为已完成的情况。

Report the outcome

报告结果

Lead with what is now true. Then identify:
  • the owning decision note and lifecycle transition;
  • behavior and authority surfaces changed;
  • acceptance evidence and commands actually run;
  • explicit gaps, blockers, or work deliberately left proposed.
Do not call a phase complete merely because Markdown exists or a checker exits zero.
首先说明当前的实际状态。然后明确：
  • 所属决策记录及其生命周期转换；
  • 已变更的行为与权威层面；
  • 验收依据及实际运行的命令；
  • 明确的缺口、阻塞点或故意保留为提议状态的工作。
不得仅因Markdown文档存在或检查工具返回零值就宣布某阶段完成。