Reusable coding standards and Claude Code skills for consistent, clean code across projects.
| Document | Description |
|---|---|
| PLANNING_GUIDE.md | First. Product planning: intake, implementation plan, task tracker — before any code |
| CLEAN_CODE.md | Language-agnostic clean code principles (SOLID, DRY, naming, etc.) |
| KOTLIN.md | Kotlin / KMP coding standards |
| SWIFT.md | Swift / iOS coding standards |
| ARCHITECTURE.md | Clean Architecture, package organization, presentation patterns |
| TESTING.md | Testing pyramid, conventions, per-layer strategies |
| KOTLIN_MULTIPLATFORM.md | KMP project init, test locations, runners, frameworks |
| EXECUTION_GUIDE.md | Rules for getting a task from to-do to committed — whoever does the work |
| TASK_LOOP.md | The machine that runs task work: gates, executor, reviewer, maintainer, landing, advancing |
| MAINTAINER_TRAINING.md | How a correction becomes a rule, and which file it goes in |
Claude Code skills (slash commands) for enforcing standards: see skills/README.md.
Copy-and-fill starting points, not documentation:
| Template | Copy to | Purpose |
|---|---|---|
| templates/review/lib/ | — runs from the submodule | Orchestrator, landing script, triage.py, prompts, schemas. Never copied, never edited |
| templates/review/project/ | .review/ |
Gates, policy, landing config, decision logs — yours to edit |
| templates/agents/ | .claude/agents/ |
diff-reviewer and maintainer subagents |
| templates/self-improve/ | — setup.sh copies the tools into the work folder |
Tools, workflows and an example project for /self-improve. Never copied into a project that is measured |
This repo is consumed as a git submodule at CodingStandards/, so every
path below is relative to your project root. Add it first:
git submodule add https://github.com/x128/CodingStandards.git CodingStandardsHTTPS on purpose. That URL is written into your project's .gitmodules and
is then used by everyone who clones it, CI included — an SSH URL there makes a
GitHub key a hard requirement for building the project. This repo is public, so
HTTPS needs no credentials at all. If you personally prefer SSH, keep the
portable URL and rewrite it locally, once, for every repo you touch:
git config --global url."git@github.com:".insteadOf https://github.com/Then paste this prompt. It is the whole setup — standards wiring and the task loop in one pass:
Read CodingStandards/CLAUDE.md and CodingStandards/TASK_LOOP.md, then set this
project up to use those standards.
1. Follow PLANNING_GUIDE.md Steps 0-3 first: ask me the intake questions, then
write IMPLEMENTATION_PLAN.md and TASK_TRACKER.md. If I say the plan already
exists, show me the file.
2. Write this project's CLAUDE.md, referencing the standards by submodule path:
CLEAN_CODE.md, ARCHITECTURE.md, TESTING.md, EXECUTION_GUIDE.md, and the language standard for
this stack (KOTLIN.md or SWIFT.md). If there is no standard for this
language, say so plainly and use the language-agnostic four. Link the
skills as CodingStandards/skills/README.md, "Setup", says.
3. Run /maintain --init to set up the review loop: detect the stack, fill in
.review/gates.sh, wire permissions, and install the routing block.
4. Stop and list the files of the first commit for me to commit: the plan, the
tracker, CLAUDE.md, .claude/skills/, and the files /maintain --init wrote. No feature code is
in them.
Report back, starting with what I have to do: the files to commit, and any
check you could not fill and why. Then the plan and tracker paths, the five
checks that run on every task with their commands, the risk paths, and
confirmation that the routing block is in CLAUDE.md. Do not write any feature code yet.
Three things in that prompt are load-bearing. Step 1 comes first and produces files — planning that stays in the conversation leaves nothing for the loop or a later reviewer to read (PLANNING_GUIDE.md Steps 1–2). The routing block is what makes later requests run the loop instead of ad-hoc edits — a setup that skips it leaves a pipeline nobody invokes. "Do not write any feature code yet" keeps setup from sliding into implementation before you have looked at the gates.
Landing starts at LANDING=off on purpose: the loop runs end to end and prints
the commit instead of making it. Turn it on in .review/land.conf only where
D-004 of the plan says the loop commits, and once you have watched a few refusals
behave.
An inherited repo, or one built before these standards, has no plan and no tracker — so nothing can tell a defect from work never started. Reconstruct the intent before reviewing or running the loop:
Follow CodingStandards/PLANNING_GUIDE.md Steps 1-2, reconstructing the plan and
the tracker from the existing code and CLAUDE.md. Ask me about anything the code
does not settle. No code changes yet.
Do the next task.
That is the whole trigger — the routing block turns any request to do task work
into a full loop run (gates → review → triage → fix rounds → landing), not just
an edit. You do not type /maintain, and there is no magic phrase: "next task",
"do T-014", and "continue" all enter the same path.
The loop is the default, never an obligation. "Just make this change", "skip the review", "I'll write this one myself" are complete instructions — see EXECUTION_GUIDE.md § Who runs the work.
MyApp/
├── CodingStandards/ # this repo, as a submodule
│ ├── CLEAN_CODE.md
│ ├── KOTLIN.md
│ ├── TASK_LOOP.md
│ ├── skills/
│ └── templates/
├── .review/ # copied out of templates/ — yours to edit
│ ├── gates.sh # the only file that knows your language
│ ├── land.conf
│ ├── REVIEW_POLICY.md
│ └── decisions/ # findings, tasks, escalations — the training log
├── .claude/
│ ├── agents/ # diff-reviewer, maintainer
│ └── settings.json # write-git deny list
└── CLAUDE.md # standards references + the routing block
- Naming conventions
- Function design (single responsibility, minimal parameters)
- Class design (cohesion, encapsulation)
- SOLID principles
- DRY, KISS, YAGNI
- Error handling
- Testing principles
- Code smells reference
- Naming conventions
- Null safety
- Error handling patterns
- State management
- Async/concurrency
- Collections
- Testing patterns
- Summary checklists
- Clean Architecture layers
- Package organization
- Presentation patterns (MVI/MVVM)
- Testing pyramid and conventions
- Per-layer test strategies
- Test naming and structure
- KMP project initialization (submodule, versions, Gradle setup)
- Test locations and runners
- Platform frameworks
- Intake questions for new products
- Implementation plan structure and rules
- Task tracker format and conventions
- Cross-check and maintenance process
- Rules that hold by hand, on request, and inside the loop alike
- One task at a time — never batch
- Who writes to git is the project's decision (D-004); read-only for agents until it is made
- The task boundary and the definition of done belong to the user
- Reporting: the user's terms, ranked by what blocks the product, findings in a file
- What it is built on: execution rules, review, gates — none of which it replaces
- Three roles: executor, reviewer, maintainer — on deterministic gates
- Layer 0 gate slots and how to wire them for any language
- JSON contracts for findings and verdicts
- Triage rules, round limits, escalation
- Landing: the eight conditions, and why commit authority is a script
- Findings are pointers, not instructions — over-fitting to the reviewer
- Advancing: when the maintainer may take the next task without asking
- Why a correction has to be a file in git, not something a session remembers
- File it by the moment it happens, not by its topic — the table of moments
- What never becomes a rule: a rejected finding, a count of rejections, a threshold for not asking
- The user is not an agent: nothing decides whether they look
- The two calls on a review: is it about the right thing, is anything left
- This project's rule versus the standard, and what it takes to move up