Claude Standards

Layered, reusable development standards for Claude Code, packaged as a plugin. This file is always loaded. The stack-agnostic rules live under .claude/rules/common/; language and framework standards load on demand as skills.

Map of the repository

CLAUDE.md                 ← you are here (always loaded entry point)
.claude-plugin/
  plugin.json             plugin manifest
  marketplace.json        marketplace catalogue (this repo is its own marketplace)
agents/                   9 specialist subagents (planner, reviewers, tdd-guide, …)
skills/
  research-reuse/         workflow: find what already exists before writing code
  plan-feature/           workflow: phased implementation plan
  tdd/                    workflow: RED → GREEN → refactor with a coverage floor
  review-changes/         workflow: quality + security review of the current diff
  ship/                   workflow: pre-commit gate, then a conventional commit
  add-standards-layer/    maintenance: scaffold a new language/framework layer
  add-agent/              maintenance: scaffold an agent and register it in the roster
  audit-config/           maintenance: audit this repo for drift
  standards-python/       Python delta over common/
  standards-typescript/   TypeScript delta over common/
  standards-fastapi/      FastAPI delta over Python
hooks/hooks.json          PostToolUse format hook (delegates to scripts/format.sh)
scripts/format.sh         self-guarding formatter runner
.claude/
  settings.json           permission allowlist for the documented toolchain
  rules/
    README.md             taxonomy + how to add a layer
    common/               stack-agnostic rules — NO frontmatter → always loaded
    _template/            blank canonical stubs to copy when adding a layer

How the layers load

Each layer is a delta over the one above — no rule is duplicated downward. See .claude/rules/README.md for the taxonomy and the reasoning behind putting language layers in skills/ rather than in scoped rule files.

On-demand content is absent in two windows: while a new file is being created, and immediately after /compact. Non-negotiable invariants therefore live in this file and in common/, never only in a layer.

Security baseline (always applies — including when creating new files)

These hold regardless of which layers are loaded:

• No hardcoded secrets. Use environment variables / a secret manager; validate required secrets at startup.
• Validate all input at system boundaries before use; never trust external data.
• Parameterized queries only — never build SQL by string concatenation.
• Escape/sanitize any user-controlled value rendered into HTML or a shell.
• Never leak sensitive data in errors or logs (credentials, tokens, cookies, auth headers).

Full checklist: .claude/rules/common/security.md.

Core conventions (full text in common/)

• Immutability — return new objects, never mutate in place. (coding-style.md)
• KISS / DRY / YAGNI; small focused files (≤800 lines) and functions (≤50 lines); early returns over deep nesting.
• TDD, 80% coverage minimum — test first (RED → GREEN → refactor). (testing.md)
• Review before merge — code-reviewer + security-reviewer; block on CRITICAL. (code-review.md)
• Research & reuse first — search existing code/libraries before writing new. (development-workflow.md)

Workflow

Research & reuse → plan → TDD → code review → commit. Each step has a skill that executes it: /research-reuse → /plan-feature → /tdd → /review-changes → /ship.

Agents and orchestration: agents.md — that table is the authoritative reviewer roster; do not invoke a reviewer that is not listed there. Commits use <type>: <description> (feat/fix/refactor/docs/test/chore/perf/ci); git-workflow.md.

Commands referenced by the rules

These appear in the rules and assume the relevant toolchain is installed in the target project:

• Python format/lint: black, isort, ruff
• Python types: mypy / pyright
• Python security scan: bandit -r <package>/
• Python tests + coverage: pytest --cov=<package> --cov-report=term-missing
• TypeScript format/lint/types: prettier, eslint, tsc --noEmit
• TypeScript tests: vitest / jest