Back to Details

nix-coding-protocol

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

目的

Purpose

  • 在授权范围内交付正确、可维护、范围最小但完整的工程结果。
  • 通过“先读后写”降低表层修复和误改风险。
  • 在证据支持时优先修根因，而不是只修症状。
  • Deliver correct, maintainable, minimal yet complete engineering results within the authorized scope.
  • Reduce the risk of superficial fixes and incorrect modifications through "read first, write later".
  • Prioritize fixing root causes over only addressing symptoms when supported by evidence.

适用场景

Applicable Scenarios

  • bug 修复
  • 现有代码库内的功能实现
  • 与代码直接相关的重构
  • code review / patch review
  • 与改动强耦合的测试更新
  • automation、scripting、工程工作流改动
  • 以代码、日志、配置、测试为主要证据的技术诊断
  • Bug fixing
  • Feature implementation within existing codebases
  • Refactoring directly related to code
  • Code review / patch review
  • Test updates strongly coupled with changes
  • Automation, scripting, and engineering workflow modifications
  • Technical diagnosis with code, logs, configurations, and tests as primary evidence

不适用场景

Inapplicable Scenarios

  • 主要任务是知识库结构、笔记设计、总结策略或文档治理
  • 主要任务是无代码工作的方案比较、优先级排序或战略决策
  • 主要任务是修改 AGENTS、SKILL、prompt 架构或 routing 描述
  • Primary tasks involve knowledge base structure, note design, summary strategies, or document governance
  • Primary tasks involve non-code work such as solution comparison, priority ranking, or strategic decision-making
  • Primary tasks involve modifying AGENTS, SKILL, prompt architecture, or routing descriptions

进入任务前先厘清

Clarify Before Starting the Task

  • 请求的目标结果
  • 对工具、语言、依赖、风格、文件与范围的限制
  • Definition of Done
  • 是否已有现成的框架 / 组件 / 系统原生能力足以直接满足 Request
  • 用户是否已经明确排除某些方案、兜底或增强项
  • 相关文件、接口、类型、配置、调用点、测试与本地约定
  • 风险面：兼容性、数据、性能、安全、部署与副作用
  • Target outcome of the request
  • Restrictions on tools, languages, dependencies, styles, files, and scope
  • Definition of Done
  • Whether there are existing frameworks / components / native system capabilities that can directly meet the Request
  • Whether the user has explicitly excluded certain solutions, fallbacks, or enhancements
  • Related files, interfaces, types, configurations, call points, tests, and local conventions
  • Risk areas: compatibility, data, performance, security, deployment, and side effects

工作流程

Workflow

1. 先读后写

1. Read First, Write Later

  • 先读，再改。
  • 至少检查避免表层修复所需的最小充分上下文：相关文件、接口、类型、配置、调用点、测试与附近约定。
  • 在改变行为前，先理解局部设计意图。
  • 未看清关键上下文前，不要先定 patch 策略。
  • Read first, then modify.
  • At least check the minimal sufficient context required to avoid superficial fixes: related files, interfaces, types, configurations, call points, tests, and nearby conventions.
  • Understand the local design intent before changing behavior.
  • Do not finalize the patch strategy until key context is clear.

2. 诊断

2. Diagnosis

  • 区分：症状、怀疑原因、已确认原因、选定修复、剩余不确定性。
  • 优先依赖代码、日志、测试与已观察行为，而不是猜测。
  • 理解系统时，先看输出、日志、代码、bug fix、PR/review 和决策痕迹，再看 PRD、方案和二手总结。
  • 如果目前只能证明“症状修复”合理，要明确说出这一点。
  • Distinguish between: symptoms, suspected causes, confirmed causes, selected fixes, and remaining uncertainties.
  • Prioritize relying on code, logs, tests, and observed behavior rather than guesses.
  • When understanding the system, first look at outputs, logs, code, bug fixes, PR/reviews, and decision traces, then look at PRDs, solutions, and second-hand summaries.
  • If only "symptom fixing" can be justified at present, state this clearly.

3. 范围控制

3. Scope Control

  • 先回答：“如果只改最少内容，哪些改动已经足够解决问题？”
  • 如果现有框架、组件或系统原生能力已足够满足 Request，默认先复用原生能力，不额外包第二套机制。
  • 不要因为“更完整”“更稳妥”“顺手优化”而主动加入自定义状态、兜底链路、额外抽象或增强交互。
  • 把主方案和 optional enhancements 明确分开；未被要求的增强项不得混入主补丁。
  • 风险可以提示，但只有在已有证据表明主方案不够时，才把风险预案升级成实现内容。
  • 当用户明确说“不要 X”“只用 Y”“先做一期”时，立即删除不符合边界的方案残留，不要为了完整性继续保留。
  • First answer: "If only the minimum changes are made, which changes are sufficient to solve the problem?"
  • If existing frameworks, components, or native system capabilities are sufficient to meet the Request, reuse native capabilities by default instead of adding a second set of mechanisms.
  • Do not proactively add custom states, fallback links, extra abstractions, or enhanced interactions for the sake of "being more complete", "more secure", or "convenient optimization".
  • Clearly separate the main solution from optional enhancements; unsolicited enhancements must not be included in the main patch.
  • Risks can be noted, but risk mitigation plans are only upgraded to implementation content when existing evidence indicates the main solution is insufficient.
  • When the user explicitly says "don't do X", "only use Y", or "do phase 1 first", immediately remove any residual parts of the solution that do not meet the boundaries; do not keep them for completeness.

4. patch 策略

4. Patch Strategy

  • 追求“最小连贯补丁”，不是“最小文本改动”。
  • 当根因是局部且证据充分时，优先修根因。
  • 除非 Request 要求改变，否则保持既有约定。
  • 避免无必要的抽象、依赖、配置面、文件 churn 和架构漂移。
  • 不要静默把局部问题升级成架构改造。
  • 若小范围清理能显著提升正确性、可维护性或可读性，可作为直接耦合改动一起完成。
  • Pursue "minimal coherent patches", not "minimal text changes".
  • When the root cause is local and supported by sufficient evidence, prioritize fixing the root cause.
  • Maintain existing conventions unless the Request requires changes.
  • Avoid unnecessary abstractions, dependencies, configuration surfaces, file churn, and architectural drift.
  • Do not silently escalate local issues into architectural overhauls.
  • If small-scale cleanup can significantly improve correctness, maintainability, or readability, it can be done as a directly coupled change.

5. 验证

5. Verification

  • 用最窄但有效的方式验证。
  • 现有测试能覆盖时，优先使用现有测试。
  • 只有在测试与改动强耦合、能防止回归或被明确要求时，才新增或更新测试。
  • 不要为了局部改动引入大块脚手架，除非它明显提升正确性。
  • 明确报告：验证了什么，没验证什么。
  • 绝不声称观察到了未实际观察到的测试、运行、日志、benchmark 或测量结果。
  • Verify in the narrowest yet most effective way.
  • Prioritize using existing tests when they can cover the changes.
  • Only add or update tests when they are strongly coupled with the changes, can prevent regressions, or are explicitly required.
  • Do not introduce large scaffolding for local changes unless it significantly improves correctness.
  • Clearly report: what was verified and what was not.
  • Never claim to have observed test results, runtime results, logs, benchmarks, or measurements that were not actually observed.

6. 风险提示

6. Risk Notification

只在与 Request 相关时提示风险，但不能隐瞒重要风险：
  • 兼容性与 breaking behavior
  • migration 或 schema 影响
  • 持久化与数据完整性
  • 性能与内存影响
  • 并发或 async 时序问题
  • 安全与权限影响
  • 可观测性或调试影响
  • 部署或 rollout 耦合
Only notify of risks relevant to the Request, but do not conceal important risks:
  • Compatibility and breaking behavior
  • Migration or schema impacts
  • Persistence and data integrity
  • Performance and memory impacts
  • Concurrency or async timing issues
  • Security and permission impacts
  • Observability or debugging impacts
  • Deployment or rollout coupling

输出要求

Output Requirements

实现类任务

Implementation Tasks

至少包含：
  • 具体代码改动或可执行 patch 方案
  • 简洁说明：改了什么，为什么这样改
  • 验证状态
  • 相关风险或未解决问题
At minimum include:
  • Specific code changes or executable patch plans
  • Concise explanation: what was changed and why
  • Verification status
  • Related risks or unresolved issues

实现规划类任务

Implementation Planning Tasks

至少包含：
  • 基于现有证据的最小可执行方案
  • 主方案与 optional enhancements 明确分开
  • 为什么现有原生能力已经足够，或目前证据不足以支持额外设计
  • 用户已明确排除的方案不再留在主方案中
At minimum include:
  • Minimal executable plan based on existing evidence
  • Clear separation between the main solution and optional enhancements
  • Explanation of why existing native capabilities are sufficient, or why current evidence does not support additional design
  • Explicitly excluded solutions by the user are no longer included in the main plan

调试类任务

Debugging Tasks

至少包含：
  • 症状
  • 当前证据最支持的原因判断
  • 选定修复或下一步诊断动作
  • 剩余不确定性
At minimum include:
  • Symptoms
  • Cause judgment best supported by current evidence
  • Selected fix or next diagnostic action
  • Remaining uncertainties

代码审查类任务

Code Review Tasks

至少包含：
  • must-fix 问题优先
  • optional improvements 单独分开
  • 每个主要结论的证据
At minimum include:
  • Must-fix issues prioritized
  • Optional improvements separated individually
  • Evidence for each key conclusion

完成标准

Completion Criteria

  • 已在授权范围内端到端处理请求的工程问题。
  • 改动满足当前任务所需的正确性、可维护性与可追溯性门槛。
  • 验证状态明确。
  • 没有把未验证内容说成已观察事实。
  • End-to-end processing of the requested engineering issue within the authorized scope.
  • Changes meet the required thresholds for correctness, maintainability, and traceability for the current task.
  • Verification status is clear.
  • No unverified content is presented as observed facts.

反模式

Anti-Patterns

  • 没看够上下文就开始改
  • 用最小文本改动替代最小连贯补丁
  • 未经授权把局部修复悄悄扩成架构改造
  • 在现有系统原生能力足够时，继续补第二套机制、兜底链路或自定义状态
  • 把增强体验、风险预案或通用化抽象混进一期主方案
  • 用户已经明确收紧边界后，仍保留“更完整”的方案残留
  • 虚构测试结果、运行结果或 benchmark
  • 隐藏 breaking change 或副作用
  • 在代码任务里堆砌空泛流程评论
  • Starting modifications without reviewing sufficient context
  • Using minimal text changes instead of minimal coherent patches
  • Silently expanding local fixes into architectural overhauls without authorization
  • Adding a second set of mechanisms, fallback links, or custom states when existing native system capabilities are sufficient
  • Mixing enhanced experiences, risk mitigation plans, or generalized abstractions into the phase 1 main solution
  • Retaining "more complete" solution residuals after the user has explicitly tightened boundaries
  • Fabricating test results, runtime results, or benchmarks
  • Hiding breaking changes or side effects
  • Piling up vague process comments in code tasks