code-that-fits-in-your-head
Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development. Use when writing or reviewing code, refactoring accidental complexity or a Big Ball of Mud, controlling technical or architectural debt in generated c
Install
npx skills add https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/code-that-fits-in-your-head
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codealive-ai-ai-driven-development@llmmart
git clone https://github.com/CodeAlive-AI/ai-driven-development.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole codealive-ai/ai-driven-development collection as a plugin from our marketplace. Git is the plain clone.
README
code-that-fits-in-your-head
Cross-agent skill for keeping software understandable and inexpensive to change. It helps prevent accidental complexity, architectural erosion into a Big Ball of Mud, and silent technical-debt accumulation—especially when coding agents can generate code faster than people can review and own it.
The skill is based on Mark Seemann's Code That Fits in Your Head: Heuristics for Software Engineering (2021), with clearly labelled editorial amendments for agent-driven development.
Use it when a task is about:
- designing complex code, APIs, domain types, validation boundaries, and invariants
- decomposing tangled functions, classes, workflows, or subsystems
- reviewing code for readability, cohesion, coupling, encapsulation, and testability
- adding features outside-in with tests and a walking skeleton
- debugging defects with reproducible tests, bisection, and tighter verification loops
- evolving legacy systems with feature flags, Strangler-style migration, reversible stages, and explicit verification
- threat-modelling endpoints or services with STRIDE
- reviewing agent-generated changes for architectural fit, verification integrity, dependency provenance, and new debt
Large tasks are not rejected because they are large. Agents can successfully implement changes spanning tens of thousands of lines when the work has coherent architecture, a clear plan, trustworthy acceptance criteria, and verifiable checkpoints. The skill targets unstructured complexity and unverifiable change—not scope by itself.
How It Works
SKILL.md contains the trigger description and top-level index. guidelines.md is the routing layer: it maps tasks, symptoms, and named practices to the smallest useful reference files.
Code examples are C#-first; every rule and the tooling tables are language-neutral.
The skill uses progressive disclosure. Load one primary file and at most one or two secondary files for the current task instead of reading the whole skill. When a rule proves repeatedly useful in a repository, operationalize it (workflows/operationalize-finding.md) so it persists as a gate and in project agent instructions.
Structure
SKILL.md # Trigger, philosophy, chapter index
guidelines.md # Task/symptom/practice routing
workflows/ # Step-by-step workflows for common engineering tasks
references/ # Focused reference packs by theme
references/tooling/ # Executable measurement commands (complexity, cycles, dead code, …)
Core themes include decomposition, encapsulation, API design, outside-in TDD, separation of concerns, teamwork and Git discipline, software evolution, troubleshooting, security, and measurement tooling. Workflows cover review, outside-in features, debugging, threat modelling, and operationalizing findings into gates.
Source Boundaries
Most reference folders summarize or operationalize ideas from Seemann's book. The references/agent-native/ folder is different: it contains local editorial additions for coding agents—verification integrity, hallucination and dependency grounding, executable guardrails, and accountable review. Editorial amendments placed in book-derived themes are explicitly marked. Do not attribute them to Seemann.
Governing Principles
- Prefer simple, cohesive designs over clever or speculative abstractions.
- Keep dependencies, side effects, and ownership boundaries explicit.
- Judge complexity across the system, not only inside individual methods.
- Require verification proportional to risk and independent of the implementation where it matters.
- Never weaken tests, types, CI, or security controls merely to make generated code pass.
- Treat generated code volume, merge rate, and approval speed as poor proxies for maintainability.
Skill manifest
Code That Fits in Your Head
Engineering heuristics for sustainable software, based on Mark Seemann's 2021 book and clearly labelled agent-era amendments.
Code examples are C#-first; every rule and the tooling tables are language-neutral.
Philosophy (Why This Skill Exists)
Software development is principally a design activity, not construction. An agent may produce most of the text, but people still review, operate, extend, and own the resulting system. These heuristics make software sustainable: understandable, resistant to architectural erosion, and cheap to change after thousands of decisions.
Core mental model from Chapter 1:
| Metaphor | What it gets right | What it misses |
|---|---|---|
| Building a house | Plans, structure | Software endures; there's no construction phase (compiling is free); dependencies can start anywhere |
| Growing a garden | Pruning, refactoring, tending | Code does not improve by itself; generated code still needs stewardship |
| Art / craft | Skill, mastery, situational knowledge | Doesn't scale; leaves newcomers without guidance |
| Engineering (the target) | Heuristics, review, sign-off, checklists | We're not there yet — physical-construction calculations don't apply |
"The act of describing a program in unambiguous detail and the act of programming are one and the same." — Kevlin Henney
Practical implications for a code agent:
- Successful software endures. Prefer changes that preserve clear boundaries and keep future change affordable.
- Complexity is the enemy, not task size. Agents can complete changes spanning tens of thousands of lines when architecture, plan, and acceptance criteria are sound. Reject needless coupling, duplication, hidden effects, and unverifiable bulk—not large scope by itself.
- Heuristics, not laws. Understand the purpose of a rule before applying or relaxing it. Project policy overrides generic formatting and workflow conventions.
- Verification is part of design. Types, tests, schemas, architecture checks, observability, and explicit acceptance criteria constrain both human- and agent-written code.
- Code is a liability. Generated volume is not progress. Prefer the smallest coherent design that solves the problem without accumulating debt.
See references/foundations/ for more on sustainability, readability, and brain-limited design.
How to Use This Skill
- Identify the user's task (writing, reviewing, debugging, security review, setting up, etc.)
- Read
guidelines.md— it maps tasks and symptoms to specific reference files - Load only the reference files relevant to the current task (progressive disclosure)
- Apply the rules; when in doubt, consult
references/practices-glossary/for cross-references - When a rule proves repeatedly useful in a repository, operationalize it (
workflows/operationalize-finding.md) so it persists as a gate and in project agent instructions.
Chapter Index
| Topic | Use when... |
|---|---|
references/foundations/ |
Sustainability, readability, complexity control, and code as liability |
references/codebase-setup/ |
Starting or inheriting a code base — git, build automation, warnings-as-errors |
references/outside-in-tdd/ |
Writing new features test-first; walking skeleton, AAA, triangulation, devil's advocate, editing tests |
references/encapsulation/ |
Designing types with invariants; DTO vs Domain Model, always-valid, Postel's law, parse-don't-validate |
references/decomposition/ |
Controlling method and system complexity; cyclomatic complexity, cohesion, coupling, feature envy, fractal architecture |
references/api-design/ |
Designing a public API; affordance, poka-yoke, CQS, hierarchy of communication, naming over comments |
references/separation-of-concerns/ |
Adding cross-cutting concerns; Decorator pattern, logging, what to log, performance vs legibility |
references/teamwork-git/ |
Writing commits, reviewing changes, continuous integration, collective ownership |
references/evolution/ |
Changing running systems; feature flags, Strangler pattern, versioning, regular dependency updates, Conway's law |
references/troubleshooting/ |
Debugging a defect; scientific method, rubber ducking, reproduce-as-test, bisection, non-deterministic defects |
references/security/ |
Threat modelling; STRIDE (spoofing, tampering, repudiation, info disclosure, DoS, elevation) |
references/code-navigation/ |
Onboarding to a code base; big picture, file organisation, cycles, property-based testing, behavioural code analysis |
references/tooling/ |
Executable measurement commands: complexity, cycles, duplication, dead code, hotspots, mutation testing |
references/practices-glossary/ |
Looking up a named book practice and its current status |
⚠️ Editorial amendments (NOT from the book)
The folder below is NOT content from Seemann's book. It contains our own additions covering agent-specific concerns the 2021 book does not address. Do not attribute these files to Seemann. See references/agent-native/knowledge.md.
| Topic | Use when... |
|---|---|
references/agent-native/ |
Agent-specific verification integrity, hallucination and dependency grounding, executable guardrails, and accountable review |
Workflows
Composite step-by-step processes live in workflows/:
| Task | Workflow |
|---|---|
| Review a pull request / piece of code | workflows/review-code.md |
| Add a new feature from scratch | workflows/add-feature-outside-in.md |
| Investigate and fix a defect | workflows/debug-defect.md |
| Threat-model a new endpoint | workflows/threat-model.md |
| Turn a recurring finding into an executable gate and persist it in project memory | workflows/operationalize-finding.md |
See guidelines.md for the full routing layer (task → file, symptom → file).
Files (ai-driven-development)
-
references
-
agent-native
-
hallucination-debugging.md 5.7 KB
Loading… -
knowledge.md 1.7 KB
Loading… -
reviewability.md 3.7 KB
Loading… -
types-as-guardrails.md 3.2 KB
Loading… -
verification-loops.md 3.9 KB
Loading…
-
-
api-design
-
examples.md 6.3 KB
Loading… -
knowledge.md 2.6 KB
Loading… -
rules.md 5 KB
Loading…
-
-
code-navigation
-
knowledge.md 4.4 KB
Loading… -
rules.md 7.4 KB
Loading…
-
-
codebase-setup
-
checklist.md 5.4 KB
Loading… -
knowledge.md 2.2 KB
Loading… -
rules.md 6.3 KB
Loading…
-
-
decomposition
-
examples.md 7.8 KB
Loading… -
knowledge.md 4.4 KB
Loading… -
patterns.md 6.3 KB
Loading… -
rules.md 5.2 KB
Loading… -
smells.md 9.9 KB
Loading…
-
-
encapsulation
-
examples.md 7.2 KB
Loading… -
knowledge.md 3.5 KB
Loading… -
rules.md 6.8 KB
Loading…
-
-
evolution
-
examples.md 7.2 KB
Loading… -
knowledge.md 2.6 KB
Loading… -
patterns.md 9.7 KB
Loading… -
rules.md 5.6 KB
Loading…
-
-
foundations
-
knowledge.md 4.6 KB
Loading… -
rules.md 5.5 KB
Loading…
-
-
outside-in-tdd
-
examples.md 8.5 KB
Loading… -
knowledge.md 3.1 KB
Loading… -
patterns.md 5.9 KB
Loading… -
rules.md 6.9 KB
Loading…
-
-
practices-glossary
-
knowledge.md 11.8 KB
Loading…
-
-
security
-
checklist.md 4.5 KB
Loading… -
knowledge.md 5.7 KB
Loading… -
rules.md 9 KB
Loading…
-
-
separation-of-concerns
-
knowledge.md 2.2 KB
Loading… -
patterns.md 6.1 KB
Loading… -
rules.md 6.5 KB
Loading…
-
-
teamwork-git
-
checklist.md 3.8 KB
Loading… -
knowledge.md 3.6 KB
Loading… -
rules.md 5 KB
Loading…
-
-
tooling
-
commands.md 4 KB
Loading…
-
-
troubleshooting
-
knowledge.md 3.4 KB
Loading… -
patterns.md 7.2 KB
Loading… -
rules.md 5.3 KB
Loading…
-
-
-
workflows
-
add-feature-outside-in.md 9.5 KB
Loading… -
debug-defect.md 6.8 KB
Loading… -
operationalize-finding.md 4.2 KB
Loading… -
review-code.md 6.9 KB
Loading… -
threat-model.md 8.1 KB
Loading…
-
-
guidelines.md 11.3 KB
Loading… -
README.md 3.8 KB
# code-that-fits-in-your-head Cross-agent skill for keeping software understandable and inexpensive to change. It helps prevent accidental complexity, architectural erosion into a Big Ball of Mud, and silent technical-debt accumulation—especially when coding agents can generate code faster than people can review and own it. The skill is based on Mark Seemann's *Code That Fits in Your Head: Heuristics for Software Engineering* (2021), with clearly labelled editorial amendments for agent-driven development. Use it when a task is about: - designing complex code, APIs, domain types, validation boundaries, and invariants - decomposing tangled functions, classes, workflows, or subsystems - reviewing code for readability, cohesion, coupling, encapsulation, and testability - adding features outside-in with tests and a walking skeleton - debugging defects with reproducible tests, bisection, and tighter verification loops - evolving legacy systems with feature flags, Strangler-style migration, reversible stages, and explicit verification - threat-modelling endpoints or services with STRIDE - reviewing agent-generated changes for architectural fit, verification integrity, dependency provenance, and new debt Large tasks are not rejected because they are large. Agents can successfully implement changes spanning tens of thousands of lines when the work has coherent architecture, a clear plan, trustworthy acceptance criteria, and verifiable checkpoints. The skill targets unstructured complexity and unverifiable change—not scope by itself. ## How It Works `SKILL.md` contains the trigger description and top-level index. `guidelines.md` is the routing layer: it maps tasks, symptoms, and named practices to the smallest useful reference files. Code examples are C#-first; every rule and the tooling tables are language-neutral. The skill uses progressive disclosure. Load one primary file and at most one or two secondary files for the current task instead of reading the whole skill. When a rule proves repeatedly useful in a repository, operationalize it (`workflows/operationalize-finding.md`) so it persists as a gate and in project agent instructions. ## Structure ```text SKILL.md # Trigger, philosophy, chapter index guidelines.md # Task/symptom/practice routing workflows/ # Step-by-step workflows for common engineering tasks references/ # Focused reference packs by theme references/tooling/ # Executable measurement commands (complexity, cycles, dead code, …) ``` Core themes include decomposition, encapsulation, API design, outside-in TDD, separation of concerns, teamwork and Git discipline, software evolution, troubleshooting, security, and measurement tooling. Workflows cover review, outside-in features, debugging, threat modelling, and operationalizing findings into gates. ## Source Boundaries Most reference folders summarize or operationalize ideas from Seemann's book. The `references/agent-native/` folder is different: it contains local editorial additions for coding agents—verification integrity, hallucination and dependency grounding, executable guardrails, and accountable review. Editorial amendments placed in book-derived themes are explicitly marked. Do not attribute them to Seemann. ## Governing Principles - Prefer simple, cohesive designs over clever or speculative abstractions. - Keep dependencies, side effects, and ownership boundaries explicit. - Judge complexity across the system, not only inside individual methods. - Require verification proportional to risk and independent of the implementation where it matters. - Never weaken tests, types, CI, or security controls merely to make generated code pass. - Treat generated code volume, merge rate, and approval speed as poor proxies for maintainability. -
SKILL.md 6.8 KB
--- name: code-that-fits-in-your-head description: Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development. Use when writing or reviewing code, refactoring accidental complexity or a Big Ball of Mud, controlling technical or architectural debt in generated code, designing APIs and invariants, adding a feature through a walking skeleton and acceptance tests, debugging a defect with reproducible tests or bisection, threat-modelling endpoints and trust boundaries with STRIDE, planning a legacy or Strangler migration with rollback, or setting up a maintainable codebase. Covers decomposition and cyclomatic complexity, cohesion, encapsulation, outside-in TDD, separation of concerns, Git/review discipline, safe evolution, and troubleshooting. Not for language syntax, framework tutorials, production incident response, or performance profiling. --- # Code That Fits in Your Head Engineering heuristics for sustainable software, based on Mark Seemann's 2021 book and clearly labelled agent-era amendments. Code examples are C#-first; every rule and the tooling tables are language-neutral. ## Philosophy (Why This Skill Exists) Software development is principally a **design activity**, not construction. An agent may produce most of the text, but people still review, operate, extend, and own the resulting system. These heuristics make software sustainable: understandable, resistant to architectural erosion, and cheap to change after thousands of decisions. Core mental model from Chapter 1: | Metaphor | What it gets right | What it misses | |----------|-------------------|-----------------| | **Building a house** | Plans, structure | Software endures; there's no construction phase (compiling is free); dependencies can start anywhere | | **Growing a garden** | Pruning, refactoring, tending | Code does not improve by itself; generated code still needs stewardship | | **Art / craft** | Skill, mastery, situational knowledge | Doesn't scale; leaves newcomers without guidance | | **Engineering** (the target) | Heuristics, review, sign-off, checklists | We're not there yet — physical-construction calculations don't apply | > "The act of describing a program in unambiguous detail and the act of programming are one and the same." — Kevlin Henney **Practical implications for a code agent:** 1. **Successful software endures.** Prefer changes that preserve clear boundaries and keep future change affordable. 2. **Complexity is the enemy, not task size.** Agents can complete changes spanning tens of thousands of lines when architecture, plan, and acceptance criteria are sound. Reject needless coupling, duplication, hidden effects, and unverifiable bulk—not large scope by itself. 3. **Heuristics, not laws.** Understand the purpose of a rule before applying or relaxing it. Project policy overrides generic formatting and workflow conventions. 4. **Verification is part of design.** Types, tests, schemas, architecture checks, observability, and explicit acceptance criteria constrain both human- and agent-written code. 5. **Code is a liability.** Generated volume is not progress. Prefer the smallest coherent design that solves the problem without accumulating debt. See `references/foundations/` for more on sustainability, readability, and brain-limited design. ## How to Use This Skill 1. Identify the user's task (writing, reviewing, debugging, security review, setting up, etc.) 2. Read `guidelines.md` — it maps tasks and symptoms to specific reference files 3. Load only the reference files relevant to the current task (progressive disclosure) 4. Apply the rules; when in doubt, consult `references/practices-glossary/` for cross-references 5. When a rule proves repeatedly useful in a repository, operationalize it (`workflows/operationalize-finding.md`) so it persists as a gate and in project agent instructions. ## Chapter Index | Topic | Use when... | |-------|-------------| | `references/foundations/` | Sustainability, readability, complexity control, and code as liability | | `references/codebase-setup/` | Starting or inheriting a code base — git, build automation, warnings-as-errors | | `references/outside-in-tdd/` | Writing new features test-first; walking skeleton, AAA, triangulation, devil's advocate, editing tests | | `references/encapsulation/` | Designing types with invariants; DTO vs Domain Model, always-valid, Postel's law, parse-don't-validate | | `references/decomposition/` | Controlling method and system complexity; cyclomatic complexity, cohesion, coupling, feature envy, fractal architecture | | `references/api-design/` | Designing a public API; affordance, poka-yoke, CQS, hierarchy of communication, naming over comments | | `references/separation-of-concerns/` | Adding cross-cutting concerns; Decorator pattern, logging, what to log, performance vs legibility | | `references/teamwork-git/` | Writing commits, reviewing changes, continuous integration, collective ownership | | `references/evolution/` | Changing running systems; feature flags, Strangler pattern, versioning, regular dependency updates, Conway's law | | `references/troubleshooting/` | Debugging a defect; scientific method, rubber ducking, reproduce-as-test, bisection, non-deterministic defects | | `references/security/` | Threat modelling; STRIDE (spoofing, tampering, repudiation, info disclosure, DoS, elevation) | | `references/code-navigation/` | Onboarding to a code base; big picture, file organisation, cycles, property-based testing, behavioural code analysis | | `references/tooling/` | Executable measurement commands: complexity, cycles, duplication, dead code, hotspots, mutation testing | | `references/practices-glossary/` | Looking up a named book practice and its current status | ### ⚠️ Editorial amendments (NOT from the book) The folder below is NOT content from Seemann's book. It contains our own additions covering agent-specific concerns the 2021 book does not address. Do not attribute these files to Seemann. See `references/agent-native/knowledge.md`. | Topic | Use when... | |-------|-------------| | `references/agent-native/` | Agent-specific verification integrity, hallucination and dependency grounding, executable guardrails, and accountable review | ## Workflows Composite step-by-step processes live in `workflows/`: | Task | Workflow | |------|----------| | Review a pull request / piece of code | `workflows/review-code.md` | | Add a new feature from scratch | `workflows/add-feature-outside-in.md` | | Investigate and fix a defect | `workflows/debug-defect.md` | | Threat-model a new endpoint | `workflows/threat-model.md` | | Turn a recurring finding into an executable gate and persist it in project memory | `workflows/operationalize-finding.md` | See `guidelines.md` for the full routing layer (task → file, symptom → file).
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.