Code standards

Write the least code that solves the problem or completes the task by identifying the right scope and surface to make the change.

Apply this to any language and repo. When unsure whether a rule fits the file in front of you, match the density and design of the most hand-written file already in the repo.

Core rules

1. Guiding Principles. Use as suggestions to make implementing the guidelines easier.

• Aggressively refactor. Do not hedge or be timid to make wide, sweeping edits that affect large areas of the codebase in pursuit of conceptual unification and redundancy elimination, especially if restoration via rollback using git history, your own memory, prior documentation, is possible.
• Keep code as modular and minimal, with responsibilities as cleanly separated as possible. Every line, type, function, structure, file, and layer is a cost a future reader pays, and they only earn their place by removing more complexity than they add, unless they add clear conceptual value.
• Analyze at a high-level view and don't treat dependencies or consumers as static. If it seems like two processes can't be unified for any reason, don't take that for granted. Consider if each reason is justified, pursuing each justification until there is an obvious resolution with clear reasoning. Ground yourself in the needs and constraints for the current tasks and the project as a whole.
• Stated plans supersede rules. If I explicitly named a future requirement or feature, it is exempt from the hard delete-requirement, unreachable-subsystem, or inline single-caller rules. Add the comment: Exempt from minimalism - {MM/DD}. Silence isn't a stated plan; cut anything implicitly kept for later.

2. Refactor process. Try each step in order, aiming for absolute minimalism and conceptual unification:

• Delete the requirement if it (either imported or created and referenced to in-repo) is not necessary as per the project's or task's needs, constraints, and minimal mandate.
• Use what already exists from another function or structure if it shares some logic with the current task. Try to use that function/structure in the current task, adapting the task logic or the function/structure to unify any shared responsibility.
• Inline at the call site if a function or variable has one caller or the other callers don't need it.
• Fold functions/structure together if any logic in the repo can be unified while removing as much of the old, fragmented logic as possible.
• Write a new function or structure if there is no shared logic between the need in question and any other responsibility in the repo.

3. Match hand-written density: a header, simple statements that are one operation, tiny helper functions, consecutive similar variable declarations, etc, should always be grouped onto one line whenever the result stays under ~100 characters, vertical whitespace scarce (6-10% blank lines). Past that ceiling, split rather than run long; most lines land between 60 and 100.
4. No scaffolding. No trait, interface, generic, or builder behind a single implementor; no helper called from one place. Code in src/ should be pure conceptual logic only.
5. No error handling for programmer error. Let an out-of-range index panic. Reserve Result/Option/exceptions for real trust boundaries: files, bytes off disk, the network, user input. Validate once, at the boundary, never at three layers.
6. Comments belong to the voice rules, not this skill. $VAULT/.claude/rules/code-comments.md owns density, tone, and what earns a doc comment.
7. Modularity. Small focused modules beat god files at every priority level. This skill trims speculative structure, never the separation of real concerns; never collapse coherent modules into one file to chase fewer files. Modules, functions, and variables should be as modulated and cleanly separated as possible, with clear call sites.
8. Git rules:

• Minimal commits, pushes, branches, and worktrees
• Ask approval for commits and pushes.
• No self-attribution. Never reference yourself as a contributor or in a commit message, PR body, etc.
• Never track a folder with a .nogithub sentinel.

Priority calibration

Each $PROJECTS project has a priority of 0-3 in $VAULT/projects/<Name>.md. Minimalism is a full mandate at the bottom and advisory at the top, because hardening outranks brevity on work that ships.

If a project has no document, treat it as priority 1-2.

File structuring

Applies to projects in $PROJECTS. The structure below is not a comprehensive list; add another file/folder if deemed appropriate.

project/
├── src/      # core logic, conceptually clean, minimal tests in-folder
├── tests/    # one folder per test kind, one flag each
│   ├── smoke/         # in-process, one promise per case, runs in seconds
│   ├── behavior/      # drives the real binary over its real protocol
│   ├── performance/   # timings and determinism, wants the machine to itself
│   ├── reports/       # DATE_smk.md, DATE_behave.md, DATE_perf.md
│   └── run-tests.sh   # --smk, --behave, --perf; writes and prints the reports
├── output/   # outputs generated by system, committed under a consistent naming scheme
│   ├── misc/ # unorganized or one-off output and end-behavior diagnostics, gitignored
├── docs/     # canonical, version-agnostic (no references to old versions)
│   ├── technical-spec.md   # agent-readable spec; rebuild the repo from this alone
│   ├── market-analysis.md  # verdict, competition, willingness to pay (P1-3 only)
│   ├── masterdoc.html      # conceptual tour at Simple/Analogies/Technical depths
│   └── branch-diff.md      # diff description of current branch vs main. Never include in or push to main.
├── README.md
└──...

• Organize all appropriate folders by subsystem, not file type. Roughly one subdirectory per concern, each with a minimal amount of entry-point files.
• Organize tests/ by test kind rather than mirroring src/ one-to-one. The test-project skill owns that shape, the runner, and the reports.
• Give a CLI or UI layer its own top-level folder instead of nesting it in src/, when it's a consumer of the core logic rather than the core logic itself.
• Reserve docs/ for canonical, version-agnostic documents (spec, market overview, masterdoc, etc). Scratch and planning notes belong in the session scratchpad, never in the repo.
• Treat docs/branch-diff.md as a per-branch scratchpad. This is the only exception to the version-agnostic and temporary documentation ban.

The HARD bans

Each of these is a default a model keeps reaching for, absent from hand-written code, and a defect if present:

• No hard-wrapped markdown. One line per paragraph or sentence; never force a line break at a column width. Hard-wrap reflows the whole paragraph on every edit and wrecks diffs/blame. Let the viewer soft-wrap.
• A helper called once from one place, or a wrapper that renames an existing call without adding behavior.
• A setter or getter-like function that could be removed by making a field public.
• Reflexive derives, a Default impl, __repr__, or a getter nothing calls (this is a language-agnostic rule).
• An error type, enum variant, or branch nothing constructs.
• A test module inside src/ (or the language's equivalent). Tests live in tests/, exercise public behavior, and earn their place by failing for a reason that matters.
• A multi-paragraph doc comment or module-header essay.
• A comment that restates the line below it, or "not X, it's Y" phrasing inside a comment.
• Running a formatter, or "fixing" unusual-but-working form that was already there.

References

• references/patterns.md for named anti-patterns to catch mid-write, each with the tell, the fix, and the case where the rule stops applying.
• references/examples.md for before/after rewrites across Python, TypeScript, Rust, and Swift.
• Comments: $VAULT/.claude/rules/code-comments.md, not a file kept here.
• Tests: the test-project skill, which owns the suite shape, run-tests.sh, and the reports.

One runnable check

A non-trivial change earns exactly one check that would fail if the change broke: one, not a suite, not a test per branch. It exercises public behavior from tests/. clean-project deletes any scratch verification beyond that at the end of the task.