Tenets of software craft

The rules AI should be using. The receipts to defend them.

Every rule here is one I've defended in code review. Each tenet has its origin, the evidence, the strongest objection and a copy-paste version for your Claude, Cursor or Copilot rules. Treat your AI like a junior developer and train it like one.

Read the tenets Implementation

51tenets9pillarsUpdated weekly · CC BY-NC 4.0

1// spine density from ring quills, plus keeper ping if coat sparse (two jobs)

2function handle(ringQuills, flankCm2) {

3 // quills in sample ÷ flank skin cm² (measurement only)

4 const d = ringQuills / flankCm2;

5 // alerting keepers is a different reason to change

6 queueKeeperPingIfSparseCoat(d < 4);

7 return d;

F1 · Single Responsibility Principle

Receipt 1 of 3

The Canon · 51 Tenets · 9 Pillars

Foundations

6What good code looks like before the framework gets a vote. Each line is a UI for the next reader, human or agent. These six tenets are the levers that make it one.Show all 6Hide

Single Responsibility Principle

Everything should do one thing and one thing only.

Intention-Revealing Names

The signature is the spec.

Don't Repeat Yourself

Every fact has one home.

Simplicity

KISS and YAGNI: no line is cheaper than the one you didn't write.

Self-Documenting Code

Code should explain itself without narration.

Encapsulation

The interface is the only contract.

Architecture

11Boundaries before patterns. Coupling is the only metric that matters.Show all 11Hide

Screaming Architecture

Folders should tell you what the app does.

Three-Tier Hoisting

Default to local. Earn each tier upward.

Stable Dependencies Principle

Volatile depends on stable, never the reverse.

Common Closure Principle

Things that change together belong together.

Thin Handlers

Entry points dispatch, they don't decide.

Bounded Contexts

Each context gets one model and one folder.

Coupling First

Pick the architecture with the weaker coupling.

Push to the Source of Truth

Run the work where the data lives.

Liskov Substitution Principle

Subtypes honour the contract.

A10

Interface Segregation Principle

Small, focused surfaces.

A11

Dependency Inversion Principle

Depend on abstractions.

Style

4How code reads on the page. The strokes and the rules that hold them in place.Show all 4Hide

Cyclomatic Caps

Hard limits beat soft conventions.

Parameter Object

Three parameters, then a struct.

Guard Clauses

Flatten the pyramid of doom.

Inline-First

Don't introduce names for nothing.

Types & Schema

4Containers that hold what they say they hold. Domain in the types, exceptions called out, casts replaced with proof, and one owner per schema.Show all 4Hide

Domain-Driven Types

Model the domain in the type system.

No Escape Hatches

The type system isn't optional.

Type Guards

Prove the type, don't assert it.

Schema Sovereignty

One owner per schema.

Process

8How good code gets written. The Foundations describe what good code looks like. The Process pillar covers the disciplines that make it the default outcome rather than the lucky one, from spec to merge.Show all 8Hide

Test-First Development

The test is the brief. Write it first.

Spec-First Execution

AC at the start, AC at the end.

Definition of Done

Done means the checklist passed.

Continuous Quality Feedback

The feedback loop is the gate.

Shift-Left Quality

Quality is part of done, not part of QA.

Leave it Better Than You Found it

Boy Scout, sharper.

Short-Lived Branches with AI+Human Review

Branch for a day, review, then merge to main.

Architecture Decision Records

Record each decision with its change.

Testing

8Probes and proofs. The instruments that keep the canon honest. Eight tenets: five about what tests prove and three about how they prove it.Show all 8Hide

TS1

Living Documentation

Tests don't lie.

TS2

Specification by Example

Domain-language Gherkin.

TS3

Parameterised Scenarios

One step definition, a table of examples, then property-based tests.

TS4

Real-Dependency E2E

Mocks hide the bugs that reach production.

TS5

Structural Assertions

Hardcoded slugs are brittleness.

TS6

Behaviour Testing

Test the public surface, never the private one.

TS7

Test Isolation

If you mock your own code, the code is wrong.

TS8

One Concept Per Test

If the name needs an and, split it.

AI Collaboration

6The pair programmer changes. The principles don't.Show all 6Hide

AI1

The Intern Pattern

Plan, approve, execute, review.

AI2

Persistent Brief

Context belongs in the repo rather than the chat.

AI3

Working Context

Context is a finite resource.

AI4

Verifiable Specs

If the agent can't grade itself, it isn't a spec.

AI5

Verify the API

Don't trust the training.

AI6

Self-Review Pass

Critique your own draft before you hand it back.

Tooling

2These tenets enforce what gates can enforce: line counts, complexity caps, duplicate text, type strictness. Everything Prickles is about beyond that boundary is what the rest of the canon teaches.Show all 2Hide

TA1

Linter as Law

Every gate is an error, never a warning.

TA2

Duplication Detection

Eyeballs miss copy-paste.

Patterns

2Prickles curates. We don't re-author the catalogue. The PT tenets discipline how to use patterns: name them and name their failure modes.Show all 2Hide

PT1

Patterns Are Vocabulary

Name them out loud, and in the code.

PT3

Every Pattern Has a Failure Mode

Read the GoF Consequences section first.