Agent skill

Code That Fits In Your Head

by CodeAlive-AI in CodeAlive-AI/ai-driven-development

Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development.

MITAuto-check passedTesting & QA

Install Code That Fits In Your Head

skills CLI
$ npx skills add CodeAlive-AI/ai-driven-development --skill code-that-fits-in-your-head -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install CodeAlive-AI/ai-driven-development code-that-fits-in-your-head --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/CodeAlive-AI/ai-driven-development.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/code-that-fits-in-your-head .claude/skills/code-that-fits-in-your-head && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
code-that-fits-in-your-head
GitHub stars
158
Token cost
~1.7k tokens
SKILL.md length
689 words
Files
65 (incl. references)
Skills in repo
22
Repo updated
First seen
Licence
MIT

At a glance

Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development.

  • Works in 5 steps: Successful software endures. Prefer… → Complexity is the enemy, not task size.… → Heuristics, not laws. Understand the… → …
  • Refactoring accidental complexity
  • SKILL.md covers Philosophy (Why This Skill…, How to Use This Skill, Chapter Index and Workflows
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Code That Fits In Your Head is an agent skill from CodeAlive-AI/ai-driven-development. 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…

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 69 other files, including reference files (for example `README.md`, `guidelines.md` and `references/agent-native/hallucination-debugging.md`).

It sits in Testing & QA, covering End-to-end testing, Threat modeling and Refactoring. It works with Git. The repository describes itself as: Practices, protocols, and skills for AI-driven software development. Skills and safety hooks for Claude Code, Codex, OpenCode, Cursor, Antigravity, and any agent supporting the… The licence is MIT.

When your agent uses it

  • Refactoring accidental complexity
  • A Big Ball of Mud
  • Controlling technical
  • Architectural debt in generated code

Example prompts

  • “/code-that-fits-in-your-head”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  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…
  3. Heuristics, not laws. Understand the purpose of a rule before applying or relaxing it. Project policy overrides generic formatting and…
  4. Verification is part of design. Types, tests, schemas, architecture checks, observability, and explicit acceptance criteria constrain both…
  5. Code is a liability. Generated volume is not progress. Prefer the smallest coherent design that solves the problem without accumulating…

What it can do on your machine

Read from SKILL.md and the folder at commit 4cfeb10. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Code That Fits In Your Head loads about 1.7k tokens when it runs, and up to ~65k if it reads all its reference files. Until then it costs about 224 tokens; SKILL.md has 689 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~224
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~65k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from CodeAlive-AI/ai-driven-development at commit 4cfeb10, republished under its MIT licence (© CodeAlive-AI). 689 words, ~1,725 tokens.

Download SKILL.mdSave it as .claude/skills/code-that-fits-in-your-head/SKILL.md (or your agent's skills folder). This skill also uses 64 other files; get the full folder from GitHub.
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:

MetaphorWhat it gets rightWhat it misses
Building a housePlans, structureSoftware endures; there's no construction phase (compiling is free); dependencies can start anywhere
Growing a gardenPruning, refactoring, tendingCode does not improve by itself; generated code still needs stewardship
Art / craftSkill, mastery, situational knowledgeDoesn't scale; leaves newcomers without guidance
Engineering (the target)Heuristics, review, sign-off, checklistsWe'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.
Show full SKILL.md (292 more words)Show less

Chapter Index

TopicUse 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.

TopicUse 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/:

TaskWorkflow
Review a pull request / piece of codeworkflows/review-code.md
Add a new feature from scratchworkflows/add-feature-outside-in.md
Investigate and fix a defectworkflows/debug-defect.md
Threat-model a new endpointworkflows/threat-model.md
Turn a recurring finding into an executable gate and persist it in project memoryworkflows/operationalize-finding.md

See guidelines.md for the full routing layer (task → file, symptom → file).

© CodeAlive-AI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 64 other files (references) in skills/code-that-fits-in-your-head of CodeAlive-AI/ai-driven-development.

  • SKILL.md
  • README.md
  • guidelines.md
  • references/agent-native/hallucination-debugging.md
  • references/agent-native/knowledge.md
  • references/agent-native/reviewability.md
  • references/agent-native/types-as-guardrails.md
  • references/agent-native/verification-loops.md
  • references/api-design/examples.md
  • references/api-design/knowledge.md
  • references/api-design/rules.md
  • references/code-navigation/knowledge.md
  • references/code-navigation/rules.md
  • references/codebase-setup/checklist.md
  • references/codebase-setup/knowledge.md
  • references/codebase-setup/rules.md
  • … and 49 more

Open the folder on GitHubat commit 4cfeb10

Compare with similar skills

Code That Fits In Your Head next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Code That Fits In Your Head compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Code That Fits In Your Head this skillCodeAlive-AI/ai-driven-development158—~1.7kAutomated safety check: PassMIT
TDD WorkflowhellangleZ/burn-in-cceverywhere-ralph11211 repos~2.4kAutomated safety check: PassNone
TDD Workflowaffaan-m/ECC276k1 repos~2.6kAutomated safety check: PassMIT
Absolute Workmaddhruv/absolute218—~5.3kAutomated safety check: PassMIT
Refactortestdouble/han279—~3.1kAutomated safety check: PassMIT
Test Guidelinesgetsentry/sentry-dart873—~3.1kAutomated safety check: PassMIT

Similar skills

  • TDD Workflow

    hellangleZ/burn-in-cceverywhere-ralph

    A skill your agent uses when writing new features, fixing bugs, or refactoring code.

    112 GitHub starsUsed in 11 repos~2.4k tokens
    Testing & QAAuto-check passed
  • TDD Workflow

    affaan-m/ECC

    Yeni özellikler yazarken, hata düzeltirken veya kod refactor ederken bu skill'i kullanın.

    276k GitHub starsUsed in 1 repo~2.6k tokens
    Testing & QAAuto-check passed
  • Absolute Work

    maddhruv/absolute

    End-to-end, phase-gated SDLC for AI coding agents: relentless design interview → reviewed spec → dependency-graphed task board → safe-wave TDD execution → verification → converge.

    218 GitHub stars~5.3k tokensUpdated 3 mo ago
    Agent WorkflowsAuto-check passed
  • Refactor

    testdouble/han

    Restructure existing code without changing its behavior, through a test-gated refactoring loop: a named target, a green suite over that target before any edit, a planned sequence of small named…

    279 GitHub stars~3.1k tokensUpdated 8 days ago
    DevelopmentAuto-check passed
  • Test Guidelines

    getsentry/sentry-dart

    Official

    Enforce Sentry Dart/Flutter SDK test conventions for naming, structure, and fixtures.

    873 GitHub stars~3.1k tokensUpdated today
    Testing & QAAuto-check passed
  • Release

    lycorp-jp/sim-use

    Cut a sim-use release end-to-end. An agent skill from lycorp-jp/sim-use.

    1.4k GitHub stars~1.7k tokensUpdated today
    Testing & QAAuto-check passed

More from CodeAlive-AI/ai-driven-development

All 22 skills in this repo
  • Investigating Repository History

    CodeAlive-AI/ai-driven-development

    Investigate GitHub repository history before risky code changes using git blame/log, GitHub PRs, review comments, squash/rebase/cherry-pick/rename heuristics, and cited evidence.

    158 GitHub stars~2k tokensUpdated yesterday
    Auto-check passed
  • Plugins Management

    CodeAlive-AI/ai-driven-development

    Create, publish, delete, and submit plugins for coding agents (Claude Code, OpenCode, Devin CLI/Desktop).

    158 GitHub stars~3.1k tokensUpdated yesterday
    Auto-check: notes
  • Windows QA Engineer

    CodeAlive-AI/ai-driven-development

    A skill your agent uses when testing Windows 11 desktop apps (WinForms/WPF/UWP) via UFO UIA/Win32 automation MCP.

    158 GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • Agentic Readiness

    CodeAlive-AI/ai-driven-development

    Audit and improve repositories for reliable agentic work across Codex and Codex App, Claude Code, and OpenCode.

    158 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed
  • Hooks Management

    CodeAlive-AI/ai-driven-development

    Manage hooks and automation for coding agents (Claude Code, Codex CLI, OpenCode, Devin CLI/Desktop).

    158 GitHub stars~4.8k tokensUpdated yesterday
    Auto-check: notes
  • Semantic Scholar Deep

    CodeAlive-AI/ai-driven-development

    Deep research over the Semantic Scholar Graph API. An agent skill from CodeAlive-AI/ai-driven-development.

    158 GitHub stars~2.2k tokensUpdated yesterday
    Auto-check passed

Works with

Questions about Code That Fits In Your Head

What does Code That Fits In Your Head do?

Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development. Code That Fits In Your Head is an agent skill from CodeAlive-AI/ai-driven-development. Software-engineering heuristics based on Mark Seemann's Code That Fits in Your Head (2021), updated for agent-driven development.

When should I use Code That Fits In Your Head?

Code That Fits In Your Head fits situations like: refactoring accidental complexity; A Big Ball of Mud; controlling technical; architectural debt in generated code.

How do I install Code That Fits In Your Head in Claude Code?

Run `npx skills add CodeAlive-AI/ai-driven-development --skill code-that-fits-in-your-head -a claude-code`. Or copy the skill folder (skills/code-that-fits-in-your-head in CodeAlive-AI/ai-driven-development) into .claude/skills/code-that-fits-in-your-head in your project. Claude Code loads it when a task matches its description.

How do I install Code That Fits In Your Head in Codex?

Run `npx skills add CodeAlive-AI/ai-driven-development --skill code-that-fits-in-your-head -a codex`. Or copy the skill folder (skills/code-that-fits-in-your-head in CodeAlive-AI/ai-driven-development) into .agents/skills/code-that-fits-in-your-head in your project. Codex loads it when a task matches its description.

Can I use Code That Fits In Your Head in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add CodeAlive-AI/ai-driven-development --skill code-that-fits-in-your-head -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/code-that-fits-in-your-head, .gemini/skills/code-that-fits-in-your-head, .github/skills/code-that-fits-in-your-head and .opencode/skills/code-that-fits-in-your-head in your project.

What does Code That Fits In Your Head need to run?

SKILL.md names no scripts, command-line tools or credentials: Code That Fits In Your Head is instructions for the agent only.

Does Code That Fits In Your Head access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Code That Fits In Your Head safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Code That Fits In Your Head use?

Code That Fits In Your Head is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Code That Fits In Your Head use?

About 1.7k tokens (SKILL.md is roughly 6.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 63k tokens, read only when the agent opens those files.

What are the alternatives to Code That Fits In Your Head?

Skills that share tags, products or a category with Code That Fits In Your Head: TDD Workflow (hellangleZ/burn-in-cceverywhere-ralph, 112 stars), TDD Workflow (affaan-m/ECC, 276k stars), Absolute Work (maddhruv/absolute, 218 stars) and Refactor (testdouble/han, 279 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Code That Fits In Your Head?

CodeAlive-AI (a GitHub organization) maintains it in CodeAlive-AI/ai-driven-development, which has 158 GitHub stars. The repository holds 22 skills in this directory. The repository was last updated on October 8, 2026.

Source: CodeAlive-AI/ai-driven-development on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.