Minimal code: a ladder for AI agents

---
name: code-minimalism
description: A write-time constraint for any agent that writes code. Before adding a line, climb a seven-rung ladder (need it at all, already in the codebase, stdlib, native platform feature, installed dependency, one line, only then the minimum), keep edits surgical, and never cut the hard floor of comprehension, validation, security and one runnable check. Use it whenever you write, fix or refactor code.
---

# Code minimalism

Adapted from ponytail by DietrichGebert (MIT): the ladder, comprehension-first, root-cause fixes, the standing rules, the hard floor, the `minimal:` comment convention (renamed from `ponytail:`) and its grep ledger, the output rule for prose, the build-not-talk boundary and the user-direction override. Added in this template: surgical scope, precedence levels 2 to 5, the scratch-copy floor item, the commit self-check and the failure-modes list. See THIRD-PARTY-NOTICE.md.

Read CONTEXT.md next to this file before you write code. It names the project's precedence overrides, its design system, its conventions and the command that runs its checks.

If CONTEXT.md is missing, or a field you need is blank, ask the user for it in the user's language before you write code, one field at a time, for example: EN "Add the command that runs your checks (tests, type check, lint):", PL „Podaj polecenie, które uruchamia Twoje testy (testy, sprawdzenie typów, lint):”. Write the answer into CONTEXT.md so you do not ask again.

## Before you start / What you need

- **An AI coding agent that reads a markdown instruction file** (required): Claude Code (https://code.claude.com/docs/en/setup, skills at https://code.claude.com/docs/en/skills), Codex CLI (https://developers.openai.com/codex/cli, AGENTS.md at https://developers.openai.com/codex/guides/agents-md) or Cursor (https://cursor.com/downloads, rules at https://cursor.com/docs/context/rules).
- **Git** (required, https://git-scm.com/downloads): surgical scope and the commit self-check are checked against `git diff`.
- **One command that runs your checks**, written into CONTEXT.md.
- **ponytail** (optional, https://github.com/DietrichGebert/ponytail, MIT): the upstream skill this template adapts. You do not need it for this template to work. Whichever you use, keep THIRD-PARTY-NOTICE.md next to this file.

This skill governs what you build. It does not govern what you say: research, reviews, audits, plans and reports keep their full depth.

## 1. Comprehend first

The ladder runs after comprehension, never instead of it.

1. Read the task in full.
2. Read every file the change touches.
3. Trace the real flow end to end: where the input comes from, what calls the code, where the output goes.
4. Only then climb the ladder.

A small diff you do not understand ships a confident wrong fix. Read fully, then be minimal.

## 2. The ladder

Before writing any code, stop at the first rung that holds:

1. **Does this need to exist at all?** If the need is speculative, skip it and say so in one line.
2. **Is it already in this codebase?** A helper, util, type or pattern a few files over: reuse it. Re-implementing what already exists is the most common kind of bloat.
3. **Does the standard library do it?** Use it.
4. **Does a native platform feature cover it?** Use it: CSS over JavaScript, a database constraint over application code, a built-in form control over a custom widget.
5. **Does an already-installed dependency solve it?** Use it. Never add a dependency for what a few lines can do.
6. **Can it be one line?** Write one line.
7. **Only then:** write the minimum code that works.

To check rung 2, search the codebase for the verb and the noun of what you are about to write (for example `format` and `price`) before writing it.

## 3. Bug fixes: root cause, not symptom

1. Reproduce the failure and read the real output before you edit.
2. Find the function where the fault lives.
3. Search for every caller of that function.
4. Fix it once, in the shared function. One guard there is a smaller diff than a guard in every caller.
5. Patching only the path the ticket names leaves every sibling caller broken. Say in your report which callers you checked.

## 4. Standing rules

- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
- No boilerplate or scaffolding "for later". Later can scaffold for itself.
- Prefer deletion over addition.
- Prefer boring over clever. Clever code is what someone decodes at 3am.
- Touch the fewest files possible. Once you understand the problem, the shortest working diff wins.
- Given two options of the same size, take the one that is correct on edge cases. Minimal means less code, not a flimsier algorithm.
- For a large request, ship the minimal version and question the rest in the same reply. Never stall.

## 5. Surgical scope

When you edit existing code, touch only the lines you can trace to the request.

Blocked:
- reformatting whitespace, quotes or commas outside the change
- adding type hints or docstrings to functions you are not modifying
- "cleaning up" unrelated imports
- refactoring adjacent helpers
- rewriting style in a file you came to touch for one line
- speculative abstraction

Allowed:
- deleting a helper whose last caller your change removed
- updating an import line for a symbol you added or removed
- adjacent edits the main change requires to compile or pass the type checker

**The trace test:** can you explain every changed line in one sentence that ends in the request? "It looked cleaner" is not a trace. Revert that line.

Unscoped edits hide the real change from reviewers and create merge conflicts with unrelated work.

## 6. The `minimal:` comment

When you cut a real corner on purpose (a global lock, a quadratic scan, a naive heuristic, an in-memory cache), mark it with a comment that names the ceiling and the upgrade path:

```python
# minimal: global lock, switch to per-account locks if throughput matters
```

```js
// minimal: linear scan over the list, index by id once it passes a few thousand rows
```

Use the comment syntax of the language, keep the literal `minimal:` prefix, and keep it on one line. The comments form a deferred-work ledger anyone can list with:

```
grep -rn "minimal:" .
```

A shortcut without this comment is not a deliberate simplification. It is an undocumented defect.

## 7. The hard floor: never minimise these away

- **Comprehension:** reading the code the change touches and tracing the real flow.
- **Input validation at trust boundaries:** anything that arrives from a user, a network call, a file or another service.
- **Error handling that prevents data loss.**
- **Security measures:** authentication, authorisation, escaping, permission checks.
- **Accessibility basics:** labels, focus order, keyboard access, contrast.
- **Anything the user explicitly asked to keep.**
- **Testing a destructive operation on a scratch copy**, never on the live, actively used repository, database or environment. This holds under time pressure too.
- **One runnable check behind non-trivial logic** (a branch, a loop, a parser, a money or security path): the smallest thing that fails if the logic breaks. No test framework, fixtures or per-function suites unless asked. Trivial one-liners need no check.

## 8. Precedence

Highest first. Where this skill conflicts with anything above it on this list, this skill yields.

1. **Explicit user direction.** If the user asks for the full version, build it without re-arguing.
2. **Security, money and tenant-boundary invariants and their tests.** Guards, idempotency keys, invariant checks and property tests on these paths are never "unrequested boilerplate".
3. **Review and audit deliverables.** Coverage maps, review reports and audit documents are the product; their length is the point.
4. **The project's design system.** Visual and motion quality in a user interface is a requirement, not over-engineering. Where the ladder says "use the native element" and the design system says otherwise, the design system wins. This skill governs code structure (abstractions, dependencies, file count, line count), not visual craft.
5. **The existing conventions of the repository.** Matching the surrounding code beats a shorter diff that does not.
6. This skill.

CONTEXT.md may name project-specific entries for levels 2 to 5. Apply them.

## 9. Prose inside a code deliverable

Code first, then at most three short lines: what you skipped and when to add it. If the explanation is longer than the code, delete the explanation. Explanation the user explicitly asked for is not bloat.

## 10. Commit self-check

Before every commit or pull request, answer in one line:

> Every line in this diff traces to the request, and the ladder was climbed.

If you cannot say that honestly, read the diff again before committing. Write the line in your reply so the user sees it.

## Failure modes to catch in yourself

- You wrote a helper, then found an equivalent one two folders away. Delete yours, use theirs.
- You fixed the caller named in the bug report and never searched for the other callers.
- Your diff for a one-line fix also renamed variables and reordered imports.
- You added a dependency to format a date the standard library already formats.
- You skipped validation on a new endpoint "to keep it minimal". The floor is not negotiable.
- You wrote a clever one-liner nobody can read. One line is rung 6, not a licence for obscurity; if the one-liner is unreadable, take rung 7.
- You left a known shortcut without a `minimal:` comment.