# Prickles > Editorial canon of 50 software craft tenets, written so working engineers and the AI agents they pair with share the same rule set. Every claim is cited; every rule ships as a downloadable file for Claude Code, Cursor, GitHub Copilot, Cline and AGENTS.md. Prickles is editorial-only — no signup, no email capture, no ads, no contribution surfaces. Single author, Adam Lewis. en-GB throughout. Each tenet has three layers: a one-line punch, a long-form explanation split into "for humans" and "for AI" halves, and a receipts layer with named-expert citations and counter-arguments addressed honestly. ## Foundations - [F1 Single Responsibility Principle](https://prickles.org/tenet/single-responsibility-principle/F1): Every thing should do one thing and one thing only. - [F2 Intention-Revealing Names](https://prickles.org/tenet/intention-revealing-names/F2): The signature is the spec. - [F3 Don't Repeat Yourself](https://prickles.org/tenet/dont-repeat-yourself/F3): Every fact has one home. - [F4 Simplicity](https://prickles.org/tenet/simplicity/F4): KISS, YAGNI, and the cheapest line is the one you didn't write. - [F5 Self-Documenting Code](https://prickles.org/tenet/self-documenting-code/F5): Code should explain itself without narration. - [F6 Encapsulation](https://prickles.org/tenet/encapsulation/F6): The interface is the only contract. ## Architecture - [A1 Screaming Architecture](https://prickles.org/tenet/screaming-architecture/A1): Folders should tell you what the app does. - [A2 Three-Tier Hoisting](https://prickles.org/tenet/three-tier-hoisting/A2): Default to local. Earn each tier upward. - [A3 Stable Dependencies Principle](https://prickles.org/tenet/stable-dependencies-principle/A3): Volatile depends on stable, never the reverse. - [A4 Common Closure Principle](https://prickles.org/tenet/common-closure-principle/A4): Things that change together, ship together. - [A5 Thin Handlers](https://prickles.org/tenet/thin-handlers/A5): Entry points dispatch, they don't decide. - [A6 Bounded Contexts](https://prickles.org/tenet/bounded-contexts/A6): One context, one model, one folder. - [A7 Coupling First](https://prickles.org/tenet/coupling-first/A7): Pick the architecture with the weaker coupling. - [A8 Push to the Source of Truth](https://prickles.org/tenet/push-to-the-source-of-truth/A8): Run the work where the data lives. - [A9 Liskov Substitution Principle](https://prickles.org/tenet/liskov-substitution-principle/A9): Subtypes honour the contract. - [A10 Interface Segregation Principle](https://prickles.org/tenet/interface-segregation-principle/A10): Small, focused surfaces. - [A11 Dependency Inversion Principle](https://prickles.org/tenet/dependency-inversion-principle/A11): Depend on abstractions. ## Style - [S2 Cyclomatic Caps](https://prickles.org/tenet/cyclomatic-caps/S2): Hard limits beat soft conventions. - [S3 Parameter Object](https://prickles.org/tenet/parameter-object/S3): Three parameters, then a struct. - [S4 Guard Clauses](https://prickles.org/tenet/guard-clauses/S4): Flatten the pyramid of doom. - [S5 Inline-First](https://prickles.org/tenet/inline-first/S5): Don't introduce names for nothing. ## Types & Schema - [T1 Domain-Driven Types](https://prickles.org/tenet/domain-driven-types/T1): Model the domain in the type system. - [T2 No Escape Hatches](https://prickles.org/tenet/no-escape-hatches/T2): The type system isn't optional. - [T3 Type Guards](https://prickles.org/tenet/type-guards/T3): Prove the type, don't assert it. - [T4 Schema Sovereignty](https://prickles.org/tenet/schema-sovereignty/T4): One owner per schema. ## Process - [P1 Test-First Development](https://prickles.org/tenet/test-first-development/P1): The test is the brief. Write it first. - [P2 Spec-First Execution](https://prickles.org/tenet/spec-first-execution/P2): AC at the start, AC at the end. - [P3 Definition of Done](https://prickles.org/tenet/definition-of-done/P3): Done means the checklist passed. - [P4 Continuous Quality Feedback](https://prickles.org/tenet/continuous-quality-feedback/P4): The feedback loop is the gate. - [P5 Shift-Left Quality](https://prickles.org/tenet/shift-left-quality/P5): Quality is part of done, not part of QA. - [P6 Leave it Better Than You Found it](https://prickles.org/tenet/leave-it-better/P6): Boy Scout, sharper. - [P7 Short-Lived Branches with AI+Human Review](https://prickles.org/tenet/short-branches/P7): Branch for a day, merge to main, review before it lands. ## Testing - [TS1 Living Documentation](https://prickles.org/tenet/living-documentation/TS1): Tests don't lie. - [TS2 Specification by Example](https://prickles.org/tenet/specification-by-example/TS2): Domain-language Gherkin. - [TS3 Parameterised Scenarios](https://prickles.org/tenet/parameterised-scenarios/TS3): Generic steps, table data, property-based next. - [TS4 Real-Dependency E2E](https://prickles.org/tenet/real-dependency-e2e/TS4): Mocks hide the bugs that ship. - [TS5 Structural Assertions](https://prickles.org/tenet/structural-assertions/TS5): Hardcoded slugs are brittleness. - [TS6 Behaviour Testing](https://prickles.org/tenet/behaviour-testing/TS6): Test the public, not the private. - [TS7 Test Isolation](https://prickles.org/tenet/test-isolation/TS7): If you mock your own code, the code is wrong. - [TS8 One Concept Per Test](https://prickles.org/tenet/one-concept-per-test/TS8): If the name needs an and, split it. ## AI Collaboration - [AI1 The Intern Pattern](https://prickles.org/tenet/the-intern-pattern/AI1): Plan, approve, execute, review. - [AI2 Persistent Brief](https://prickles.org/tenet/persistent-brief/AI2): Context belongs in the repo, not the chat. - [AI3 Working Context](https://prickles.org/tenet/working-context/AI3): Context is a finite resource. - [AI4 Verifiable Specs](https://prickles.org/tenet/verifiable-specs/AI4): If the agent can't grade itself, it isn't a spec. - [AI5 Verify the API](https://prickles.org/tenet/verify-the-api/AI5): Don't trust the training. - [AI6 Self-Review Pass](https://prickles.org/tenet/self-review-pass/AI6): Draft, then critique, then fix. ## Tooling - [TA1 Linter as Law](https://prickles.org/tenet/linter-as-law/TA1): Hard limits beat soft conventions. - [TA2 Duplication Detection](https://prickles.org/tenet/duplication-detection/TA2): Eyeballs miss copy-paste. ## Patterns - [PT1 Patterns Are Vocabulary](https://prickles.org/tenet/patterns-are-vocabulary/PT1): Name them out loud — and in the code. - [PT3 Every Pattern Has a Failure Mode](https://prickles.org/tenet/every-pattern-has-a-failure-mode/PT3): Read the GoF Consequences section first. ## Implementation - [Rule packs for AI coding agents](https://prickles.org/implementation): Drop-in rule files for Claude Code, Cursor, GitHub Copilot, Cline and AGENTS.md (Codex and most generic agent SDKs). ## About - [Why Prickles](https://prickles.org/why): Why the site exists and what it covers. - [How Prickles works](https://prickles.org/how): Methodology, provenance, machine-assistance disclosure, versioning. - [Who built Prickles](https://prickles.org/who): About the author. ## Optional - [Feedback](https://prickles.org/feedback): Form for sending corrections and disagreement. - [Search](https://prickles.org/search): Search the canon.