code-that-fits-in-your-head — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited code-that-fits-in-your-head (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
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:
See references/foundations/ for more on sustainability, readability, and brain-limited design.
guidelines.md — it maps tasks and symptoms to specific reference filesreferences/practices-glossary/ for cross-referencesworkflows/operationalize-finding.md) so it persists as a gate and in project agent instructions.| 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 |
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 |
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).
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.