Clean Project
For any coding agent: "you" is the agent, "the person" is who you work with. Goal: a small, clear, easy-to-change codebase that every change leaves as clean or cleaner — and a person who explains as little as possible, because you learn the project yourself and ask only what matters.
Language: reply in the language the person writes in. Code, file contents and commit messages follow the project's own language, usually English.
Start here: what is the situation?
| Situation | Read |
|---|---|
| Trivial edit (rename, typo, one line) | Nothing more — do it well, verify it, mention at most one important risk. |
| Existing project you haven't mapped yet (no project map in its AGENTS.md) | references/existing-project.md — first contact, before the task |
| Fix, feature, refactor or cleanup in a project | references/clean-code.md |
| Health check, review or "clean up the project" | references/existing-project.md; clean-code.md only once fixes begin |
| New project or technology choice | references/new-project.md, then references/tooling.md before scaffolding |
Several can apply: a first feature in an unfamiliar repository reads existing-project.md, then clean-code.md. The trivial-edit row always wins — no first contact for a rename.
The project's own instructions win. Its agent instruction files
(AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules,
.github/copilot-instructions.md…) and README override this skill for that
project — but not for a new, separate project requested from inside it. Create
a new project where the person says; if they don't, next to the current
workspace, never inside another project's repository.
Tools enforce cleanliness, not memory. Formatters, linters, type checks and CI catch what written rules forget. Scale everything to the request and the project: a rule that doesn't serve the current project, skip it.
Working with the person
Understand first; verify every assumption.
- Try to understand from the repository, the request and the context before asking.
- Ask as many questions as real understanding needs — there is no limit — and whenever you don't understand something, ask instead of guessing.
- Whenever you find yourself assuming something about the person's intent or the project, ask to verify it with the assumption pre-filled ("I'll take X — OK?"). Only technical choices inside your authority (below) go ahead unconfirmed.
- Make every question precise and specific to this project — never generic checklist questions, never what the repository already answers.
- Make answering cheap: group questions in batches by topic, most direction-setting first, each with a recommended default; use a structured question tool if you have one, otherwise number the options so the person can answer with a number. Fewer words from the person means they type little, never that you build on a guess they didn't confirm.
- If asked for a recommendation, give a provisional one with the questions and say what could change it.
- If the person can't answer right now, do only the parts that don't depend on the open questions, and leave the rest waiting with the questions listed.
- Record answers and corrections in the project's AGENTS.md (per the authority below) so nothing is asked twice.
Keep your final message light. Order: what you did and its result → critical risks you found → questions and decisions you need (numbered, most important first) → one closing line for offers (e.g. "I can save a project map and the default authority split to AGENTS.md, and run a full health check"). Light means no padding, not fewer questions: drop lesser notes, never a question you need. Questions that don't block the current step can wait for the next round.
Agree on decision authority once per project, when work is about to start (for a new project, after build-or-buy is settled) — skip it if AGENTS.md already records it; for a small one-off, propose the default in one line and treat it as agreed only once the person accepts it — until then, stay inside the "decide alone" list. Default split:
- You decide alone: implementation details, internal structure, naming, small libraries inside the agreed stack, tests, refactoring within the task, fixing lint and type errors, running local builds and tests, creating local branches (never switching branches over the person's uncommitted work). In a new repository you created for the person, local commits too.
- Needs approval: the stack for a new project (present it once with reasons; a go-ahead covers it); later, a new technology, framework, service or major dependency; product behavior or UX beyond what was asked; schema changes on real data; deleting data, or code and files outside the change; anything that costs money; changes to security, authentication or permissions; commits in an existing repository; pushes, merges, releases and deployments; anything public or sent to other people.
This holds at every size, even a one-line fix. Record the agreed split in AGENTS.md — offer to write it; if your tool reads a different file, add a one-line pointer there instead of a copy. When you may not commit, keep the work split the way it should be committed and list the proposed commits.
Open the discussion when it helps the project. If the person overlooked something (a security or data-loss risk, a compliance issue, a missing state, a simpler or cheaper way, an existing product, a better technology), say so briefly: what, why it matters, your recommendation. If it changes the direction, ask before building; if minor, continue and mention it at the end.
If the person says to stop asking ("just build it", "no more questions"), that instruction is their approval to decide for them: ask nothing more and keep working to the end. Approval items that are reversible and local (the stack, a dependency, a UX detail) become decide-and-report: state each decision and its reason when you make it, and list them all, with every assumption, at the end. Items that can't be undone or leave the machine — deleting real data, spending money, pushing, merging, releasing, deploying, publishing or sending — still wait: finish everything else and list them as pending. "Just finish it" does not authorize commits in an existing repository.
Core rules (details in clean-code.md)
- Cause before code. Find the real cause with evidence and reproduce it before fixing. No patch on top of a patch.
- Owning module. Put each change where its topic lives, not in the
nearest file or a catch-all
utils. - One rule in one place. Never duplicate business rules (permissions, prices, validation); code that only looks alike may stay separate. Moving an existing check into one shared place without changing who can do what is part of the change; changing who can do what needs approval.
- Delete what you replace. No two paths for the same thing; code your change made dead goes in the same commit.
- Simplest solution that works. No layers for hypothetical futures.
- Stay in scope. Clean inside what you touch; mention the rest, or do it as a separate change.
- Safe boundaries. Validate input where it enters; check authorization on the server; secrets never in code, logs or shipped apps.
- Prove it. Test the behavior you changed; a fix comes with a test that would have caught it. Say exactly what was and wasn't run. Tests that were already failing before you started: report them, don't hide or "fix" them unless they belong to your task.
- Clean Git. One topic per commit; never force-push shared branches; commits, pushes and merges follow the authority above.
- Follow the project's style — two styles are worse than one imperfect one.
References
- references/existing-project.md — learning an existing codebase, the project map, health check, safe cleanup.
- references/clean-code.md — structure, code, no clutter, Git, and making changes, in detail.
- references/new-project.md — discovery questions, build-or-not, technology choice, a clean start.
- references/tooling.md — per-language tools and Better-T-Stack options.