nix-coding-protocol

Purpose

• Deliver correct, maintainable, minimal-scope but complete engineering results within the authorized scope.
• Reduce surface-level fixes and the risk of erroneous changes through "read before write."
• When supported by evidence, prioritize fixing the root cause rather than only the symptom.

Applicable scenarios

• Bug fixing
• Feature implementation within an existing codebase
• Refactoring directly related to code
• code review / patch review
• Test updates strongly coupled to changes
• Automation, scripting, engineering workflow changes
• Technical diagnosis using code, logs, configuration, and tests as primary evidence

Inapplicable scenarios

• The main task is knowledge base structure, note design, summarization strategy, or documentation governance
• The main task is solution comparison, prioritization, or strategic decision-making for non-code work
• The main task is modifying AGENTS, SKILL, prompt architecture, or routing descriptions

Clarify before starting the task

• The target outcome of the request
• Constraints on tools, languages, dependencies, style, files, and scope
• Definition of Done
• Whether existing frameworks / components / native system capabilities are sufficient to directly satisfy the Request
• Whether the user has already explicitly excluded certain solutions, fallbacks, or enhancements
• Relevant files, interfaces, types, configuration, call sites, tests, and local conventions
• Risk surface: compatibility, data, performance, security, deployment, and side effects

Workflow

1. Read before write

• Read first, then change.
• At minimum, inspect the minimal sufficient context needed to avoid surface-level fixes: relevant files, interfaces, types, configuration, call sites, tests, and nearby conventions.
• Before changing behavior, first understand the local design intent.
• Do not decide on a patch strategy before clearly understanding the key context.

2. Diagnosis

• Distinguish: symptoms, suspected causes, confirmed causes, chosen fix, and remaining uncertainty.
• 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/review, and decision traces, then look at PRDs, proposals, and secondhand summaries.
• If currently only a "symptom fix" can be justified, state this explicitly.

3. Scope control

• First answer: "If only the minimum content is changed, which changes are already sufficient to solve the problem?"
• If existing frameworks, components, or native system capabilities are already sufficient to satisfy the Request, by default reuse the native capabilities first and do not wrap a second mechanism around them.
• Do not proactively add custom state, fallback paths, extra abstractions, or enhanced interactions just because they are "more complete," "safer," or a "convenient optimization."
• Clearly separate the main solution from optional enhancements; enhancements that were not requested must not be mixed into the main patch.
• Risks may be flagged, but only when existing evidence shows the main solution is insufficient should risk contingencies be escalated into implementation content.
• When the user explicitly says "do not do X," "only use Y," or "do phase one first," immediately remove remnants of solutions that do not fit the boundary; do not keep them for the sake of completeness.

4. Patch strategy

• Pursue the "minimal coherent patch," not the "minimal textual change."
• When the root cause is local and the evidence is sufficient, fix the root cause first.
• Unless the Request requires a change, keep existing conventions.
• Avoid unnecessary abstraction, dependencies, configuration surface, file churn, and architectural drift.
• Do not silently escalate a local problem into an architectural overhaul.
• If a small-scope cleanup can significantly improve correctness, maintainability, or readability, it may be completed together as a directly coupled change.

5. Verification

• Verify in the narrowest but effective way.
• When existing tests can cover it, prefer using existing tests.
• Only add or update tests when they are strongly coupled to the change, can prevent regressions, or are explicitly required.
• Do not introduce large blocks of scaffolding for a local change unless it clearly improves correctness.
• Clearly report: what was verified and what was not verified.
• Never claim to have observed tests, runs, logs, benchmarks, or measurement results that were not actually observed.

6. Risk Disclosure

Only flag risks when they are relevant to the Request, but do not conceal important risks:

• Compatibility and breaking behavior
• Migration or schema impact
• Persistence and data integrity
• Performance and memory impact
• Concurrency or async timing issues
• Security and permission impact
• Observability or debugging impact
• Deployment or rollout coupling

Output Requirements

Implementation-type tasks

At minimum include:

• Specific code changes or an executable patch plan
• A concise explanation: what was changed and why it was changed this way
• Verification status
• Relevant risks or unresolved issues

Implementation-planning-type tasks

At minimum include:

• The minimal executable plan based on existing evidence
• The main plan and optional enhancements clearly separated
• Why existing native capabilities are already sufficient, or why the current evidence is insufficient to support additional design
• Options the user has explicitly excluded are no longer kept in the main plan

Debugging-type tasks

At minimum include:

• Symptoms
• The causal judgment best supported by the current evidence
• The selected fix or next diagnostic action
• Remaining uncertainty

Code-review-type tasks

At minimum include:

• Must-fix issues first
• Optional improvements separated out
• Evidence for each major conclusion

Completion Criteria

• The engineering problem in the request has been handled end to end within the authorized scope.
• The change meets the correctness, maintainability, and traceability thresholds required for the current task.
• Verification status is clear.
• Unverified content is not presented as observed fact.

Anti-patterns

• Starting to change things before seeing enough context
• Replacing the minimal coherent patch with the minimal textual change
• Silently expanding a local fix into an architectural overhaul without authorization
• Continuing to add a second mechanism, fallback path, or custom state when the existing system's native capabilities are sufficient
• Mixing experience enhancements, risk contingencies, or generalized abstractions into the phase-one main plan
• After the user has explicitly tightened the boundaries, remnants of a "more complete" solution are still retained
• Fabricated test results, run results, or benchmarks
• Hiding breaking changes or side effects
• Padding code tasks with vague process comments