AI_CONTRIBUTING.md - rules for agents to modify my code

AI_CONTRIBUTING.md

AI Contributing Requirements

These rules apply to all AI-assisted changes in this repository.

Workflow

1. Read every file you plan to change and directly related modules.
2. Summarize current behavior and invariants.
3. Propose a minimal patch plan (diff and rationale).
4. Obtain user approval before editing code.
5. Affirm all Completion Gates are met.

Code Design

• Prioritize correctness, then idiomatic and reviewable code.
• Prefer clarity over cleverness.
• Write small single-purpose functions with clear names.
• Expand to single-purpose modules composed of consise functions.
• Prefer decomposition over accretion: extract helpers as behavior grows.
• Prefer canonical, widely understood solutions.
• Treat these rules as defaults; escalate exceptions before implementation.
• Keep diffs focused; avoid idiosyncratic churn.
• Write comments that explain enduring intent or constraints, no editorial comments.

Naming

• Naming must be semantic.
• Do not encode type or structural primitives in names (int, object, string, etc)
• Avoid namespace prefixes or suffixes. If everything starts with or ends with "fix" nothing should.
• Use names like State, Context, or Manager only if a clear abstraction requires it at a systemic level.

Abstraction

• Abstract to remove duplication or enforce invariants.
• Prefer concrete types over generic wrappers.
• Avoid unwrap/expect outside of tests. Use effective error handling patterns including Result and Optional.

Dependencies and Imports

• Prefer the standard library.
• Add external crates only with user approval.
• Declare imports at the top of each module; keep them explicit and organized so dependencies are clear

Tests

• Test project behavior and contracts, not language or dependency internals.
• Avoid vacuous tests: removing or breaking target code must cause a test to fail.
• Unit tests are required to be hermetic: no network or external assets.
• Add or update tests for every behavior change.

Completion Gates

Before marking work complete, run and report:

1. cargo check
2. cargo fmt --check
3. cargo clippy --all-targets --all-features --no-deps -- -D warnings
4. All tests pass (unit, doc, and integration)

Do not mark work complete until all gates pass.

Reviewed by ChatGPT 5.3 Codex and Claude Opus 4.6. Both agents claim they can follow it unambiguously.