Skip to content

STYLE.md

Latest commit

 

History

History
51 lines (36 loc) · 3.75 KB

STYLE.md

File metadata and controls

51 lines (36 loc) · 3.75 KB
Raw

STYLE.md — Repo style anchor

A one-page description of the formatter, linter, naming, and structural conventions the agent must respect. Without this file, every fresh agent session reintroduces drift, and 07-refactor-prune has nothing to anchor on.

Lite mode is fine. A short paragraph + tool list beats a long unenforced manifesto. Update it when the lint config changes, not on every PR.

Tooling (authoritative — agent must read these before editing)

Concern Tool / config file Notes
Format <prettier / black / rustfmt / gofmt / dprint> — config: <path> Run on save; CI rejects unformatted diffs.
Lint <eslint / ruff / clippy / golangci-lint> — config: <path> Warnings are errors in CI.
Type-check <tsc / mypy / pyright> — config: <path> Strict mode.
Test runner <vitest / jest / pytest / cargo test> Determinism rules in ARCHITECTURE.md.
Pre-commit <husky / lefthook / pre-commit> — config: <path> Wire tools/hooks/commit-msg and tools/hooks/pre-push.
Editor .editorconfig Honored by every editor.

If a section's tool is "none yet", say so explicitly. Empty rows invite the agent to invent.

Naming

  • Files: <kebab-case | snake_case | PascalCase>. State the rule per directory if it varies (e.g. components vs. utils).
  • Symbols: <camelCase functions / PascalCase types / SCREAMING_SNAKE constants>.
  • Tests: test names must contain the requirement id (R-014, SEL-08). See 09-review-traceability.
  • Branches: F-NNN-<slug> for feature work, fix/F-NNN-<slug> for bug fixes.
  • Commits: F-NNN: … / fix(F-NNN): … / chore: / docs: / docs(article): / test: / refactor:. Enforced by tools/hooks/commit-msg.

Structure

  • Directory layout: point to ARCHITECTURE.md if you have one; otherwise list the top-level dirs and their purpose.
  • Layer rules: authoritative in ARCHITECTURE.md. Cross-layer imports require an ADR. Critic skill checks this.
  • One module, one purpose. If a file grows past <N> LOC or <M> exports, split.
  • Tests live in <tests/ | __tests__ | foo_test.go | foo.test.ts>. Be explicit; the audit script needs to find them (TESTS_DIR env var in tools/audit.sh).

Comments and docs

  • No "what" comments. The code says what; comments say why.
  • No commented-out code. Delete; git is the archive.
  • Docstrings on public surface only. Internal helpers do not need docstrings unless behavior is non-obvious.
  • TODO format: TODO(F-NNN): <one-sentence reason>. Untagged TODOs are flagged by audit.sh (heuristic).

Diff hygiene

  • No mixed-purpose diffs. A slice that adds a feature and refactors an unrelated module is two slices.
  • No formatter churn. If the formatter wants to rewrite a file you didn't touch, leave it. File a separate chore: PR.
  • No silent dependency adds. Every new dep gets a written justification (license, size, maintenance, alternative considered) in ARCHITECTURE.md Tech Stack or an ADR; lockfile changes require an explicit prompt.
  • Net diff size budget: soft cap <200 LOC added per slice (excluding lockfile and snapshot updates). Larger requires a Diff Size Waiver line in F-NNN.md with rationale. Enforced by tools/audit.sh --diff-size.

When this file is wrong

If a rule here contradicts current code in >5 places, the rule is dead — supersede it (write what the code actually does, file an ADR if it's a real change). Don't leave aspirational rules that nobody follows; they train the agent to disregard the file.