Claude Code — Best Practices
Hi!
This used to be an article about working with Cursor. I rewrote it.
Not because Cursor got worse. The way of working changed: the agent is no longer "smart autocomplete" but an executor whose workplace you prepare, and how well that workplace is prepared affects the result far more than how elegantly you phrased the request. Preparing it doesn't mean describing everything, though: a current model reads the code by itself, faster than you could retell it. What's worth writing down is what the code doesn't contain.
What follows is about Claude Code. What to put in the repository, how to plan work, how to avoid burning through context and money. The examples come from a working project where all of this is set up and has survived several months of real development; the numbers come from there too, not from my head. The snapshot of that project dates from August 2026; what changed in it over the next three months, and why, is in the section "Three months later".
Context: a price, not a wall
The model has a context window, and the entire session fits into it: your messages, every file read, the output of every command, including that three-hundred-line log the agent printed once and never looked at again. A single debugging session easily eats tens of thousands of tokens.
Not long ago that was the main constraint. Now most models have a million-token window, and Claude Code compacts the history by itself before it fills up, so running out of context is rare. Anthropic's official guidance now lists "The context window is your main constraint, manage it aggressively" among the advice that has aged.
But context hasn't stopped being a price. Every request sends the model the whole conversation again: at a discount while the cache is warm, at full price after a pause (on a subscription the cache lives about an hour, on an API key five minutes). A session holding three unrelated tasks re-reads all three on every turn of the fourth. Nor has it stopped being noise: two failed attempts left in the history get re-read along with the good one, and an agreement made only in chat may not survive compaction.
Hence the conclusion everything else grows from. Context still has to be managed deliberately: you decide what goes in and what doesn't. Only now it's for the sake of cost and focus, not out of fear that the window will run out.
Give the agent a way to check itself
This is the first thing worth setting up, and the thing most often skipped.
The agent stops when the work looks done. If there is nothing to check it with, "looks" is the only signal available, and you become the checker. Every mistake waits for you to notice it.
Give it something with an unambiguous pass/fail and the loop closes by itself. The agent edits, runs the check, reads the result, repeats. The check can be a test suite, a build exit code, a linter, a script that diffs output against a fixture, a screenshot to compare with a design.
The difference shows up right in how you phrase the task:
✗ write an email validation function
✓ write an email validation function. Examples: user@example.com is valid, invalid is not, user@.com is not. After implementing, run the tests and show the output
✗ the build is failing
✓ the build fails with this: [error text]. Fix the cause, not the symptom, and make sure the build passesIn my project the check is baked into the commit rule: before a commit the type check, the build and two content validators are run without exception. Not "preferably" but "always", with a note that the gate results go into the report as they really are, not as "everything looks green".
How strictly to hold the check is up to you, and there are now four steps. In the prompt: "run the auth tests and keep going until they pass" — the agent decides for itself when it's satisfied. As a goal: /goal sets a condition that a separate model checks against the conversation after every turn, and the agent keeps going until it's met; this matters mostly for long background runs, where it sometimes ends a turn with a progress summary while items are still open. As a Stop hook: your script runs every time the agent tries to end its turn, and exit code 2 sends it back to work. That is enforced by Claude Code itself, not by the model. And by other eyes: /code-review checks the diff in a fresh subagent that never saw your conversation and isn't infected by the reasoning the code grew out of.
For what tests and type checks don't catch there is /verify: the agent builds and runs the app itself and looks at the result.
And ask for evidence: test output, the command itself, a screenshot. Reading evidence is faster than re-checking by hand. And for a session you weren't watching it is the only way to know what happened.
Explore first, then plan, then code
Ask for code straight away and you get a tidy solution to the wrong problem.
Claude Code has a separate planning mode — Shift+Tab, or /plan in front of a single prompt: the agent reads files, runs commands to explore and writes a plan, but doesn't touch the source. The working cycle comes out like this: understand the relevant part of the code → draw up a plan → approve it, and the mode switches itself off → implement → commit.
Read the plan with your own eyes. It is the cheapest point of intervention: fixing a paragraph of a plan takes a minute, redoing an implementation takes half an hour.
For a big task the "let the agent interview you" trick works well. You describe the idea in one paragraph and ask it to ask questions: about the implementation, the edge cases, the things you might have missed. At the end it writes a specification into a file. Then a fresh session with clean context and a request to implement from that spec.
I want to build [one sentence about the feature]. Interview me in detail,using the question tool.
Ask about implementation, UI, edge cases, risks and trade-offs. Skip theobvious, dig into the hard parts I might not have considered.
When we're done, write the full specification into SPEC.md.Just don't turn it into a ritual. If an edit can be described in one sentence, no plan is needed: the extra round costs more than it returns. For a clear task the first plain prompt is usually enough: the agent will read the code it needs by itself.
Three levels of configuration
Knowledge reaches the agent in three ways, and they are not interchangeable.
Project instructions are read at the start of every session. Facts that are always needed go here: how to build, how to run the tests, how this project differs from a typical one. Anthropic's recommendation is to stay under two hundred lines, and that isn't a formality. The longer the file, the worse its own instructions are followed.
A good test for every line: if I remove this, will the agent start making mistakes? No — remove it. Anthropic's test is stricter still: could the agent find this by reading the code, and would it actually go and look? If both answers are yes, the line is redundant. That is why describing the architecture and the folder layout in the instructions is no longer worth it: the agent reads the repository itself, faster than you could explain it. What's needed is what isn't in the code: a decision made on a call, a deploy process living in one person's head, the environment variable the integration tests need, the place where the code is misleading.
/init builds a starting version of the file, and from there the work is mostly deleting. And /doctor prompt-audit goes through the instructions, rules and skills looking for directions written for older models, references to files that don't exist and contradictions between files; it proposes edits but changes nothing without asking.
Rules live as separate files in the rules directory, one file per topic, and load the same way. They can be scoped by path patterns, and then a rule is pulled in only when the agent touches matching files:
---paths: - "src/api/**/*.ts" - "apps/backend/**/*.ts"---
# Rules for the API
- Every endpoint validates its input, no exceptions.- Errors are returned in the shared `ErrorResponse` format.- A new endpoint is described in api.md first, then written in code.A rule with patterns is pulled in when the agent reads or edits a matching file. A nuance that's easy to miss: on compaction such a rule leaves together with the history and comes back only when the agent touches a matching file again. Rules without patterns and the root instructions file are re-read from disk after compaction.
Skills are knowledge on demand. A directory with a file inside; the body enters the context only when the task matches it or when you invoke the skill yourself. That is why big reference documents should be skills: while dormant, all they leave in the context is a name and a description. And a procedure with side effects, like cutting a release, is worth marking disable-model-invocation: true: then the agent won't start it on its own, only you can, with /name, and it takes no room in the list.
The layout I use:
- a fact needed always → project instructions;
- mandatory behaviour → a rule;
- a procedure or reference needed sometimes → a skill;
- something that must (or must never) happen every time, without the model's involvement → a hook or a deny rule in the permission settings.
The last point stands apart. Everything above is text the model reads and usually follows. A hook is code that runs regardless of its decision. Critical behaviour should be a hook, not a paragraph in the instructions. The reverse holds too: a hook for something that is really a preference does harm. Preferences have exceptions, and a model with the code in front of it usually judges better whether a rule fits the case than you did writing it in advance. Anthropic advises keeping the set of hard prohibitions small: if you've got around forty of them, most are matters of taste. I go through hooks, every event and working examples, in a separate article.
And all of it is prompts
A thought I arrived at late, and should have started with.
Project instructions, rules, skills, subagent descriptions — none of that is configuration. Those are system prompts that somebody (you) writes once and the model reads every session. The difference between "the agent constantly does the wrong thing" and "the agent behaves predictably" is very often the difference between a sloppily and a carefully written prompt.
Which prompt-engineering techniques actually pay off in these files:
- Structure and delimiters. Headings, lists, explicit blocks: the model parses structured text more reliably than solid prose, and you gain the ability to reference a specific chunk from another rule. More on delimiters and prompt structure.
- A hierarchy of rules. Past five rules they start to conflict, and you have to state outright which one wins. In my setup "don't commit unless asked" sits above the pre-commit review rule, and the text says so in words rather than implying it. There is a separate section on setting up a rule hierarchy.
- Positive phrasing instead of prohibitions. "Leave the changes in the working tree and describe what you did" works better than "don't commit". Prohibitions alone leave the model without a model of behaviour.
- A calm tone instead of shouting. IMPORTANT and capital letters were needed by older models. Current ones follow a plainly worded line, and pressure makes them apply the rule too broadly, including where it doesn't fit.
- Examples instead of descriptions. A "bad like this / good like that" pair in a rule is worth three paragraphs of explanation. It is ordinary few-shot, just applied to a project's configuration.
- An explicit output format. If you want a particular shape of report, it has to be described, and better still shown. On output format control, same place.
- Context economy. Every line of instructions and rules is paid for in every session, so a superfluous word here costs more than in an ordinary prompt. This is exactly what the prompt article calls context engineering.
One more observation from practice: describe not only what to do but which mistake the rule prevents. A model that understands what it is being insured against applies the rule far better to a situation the text doesn't spell out. That is why half of my rules open with a paragraph along the lines of "the known failure looks like this".
The full walkthrough of the techniques is in the article on prompt engineering; further down I'll be linking to specific sections of it.
What it looks like on a live project
From here I'm showing a working repository as it was in August 2026: nine rules, an API reference, a hundred and two skills and a task tracker right inside the project. None of it appeared at once; it grew out of situations where the same thing had to be explained for the third time.
Rules
A rule is what the agent must always follow. Each lives in its own file and ends with a checklist that shows whether it was followed or not.
Here is an entire rule, the shortest of mine:
# No commits until asked
**Do not run `git commit` (or push, PR, merge) until the user has askedfor it directly, in their own words.**Finished work, a green build and a feeling of "seems done" are notpermission.
Made the edits — leave them in the working tree, say briefly what changed,and stop. Not sure whether you were asked — don't commit, ask.
## Checklist
- [ ] No commit, push or PR without an explicit request in the user's words.- [ ] Work left in the working tree, the changes described.- [ ] When unsure, a question was asked instead of a commit.Looks like overkill. Right up to the first time the agent decides that green tests mean it may as well commit, and carries your half-finished experiments into history.
Now the other eight. My originals are written in English (a historical accident, the rules travelled between projects), and the quotes below are from them.
The pre-commit review
The longest rule; it comes into force once a commit has actually been asked for. Four stages: read the whole diff hunk by hunk; examine everything the changes touch beyond the diff, meaning callers, contracts and the documentation those edits have just made stale; hunt for defects; pronounce a verdict.
There are exactly three verdicts, worded so the agent has nowhere to wriggle:
PASS — nothing found, or everything found is already fixed and re-verified.
FIX, THEN PASS — real but fixable findings. Fix them yourself, immediately, re-run the review on the fixed state and tell the developer plainly what was found and what was fixed. Fixing is the default: problems are never parked "for later" and never merely mentioned in the report.
STOP — a serious problem (data loss, a security hole, a broken contract, the change contradicting its own requirement) or a genuine fork where both designs are defensible and the choice is the developer's. No commit. Explain simply and concretely what the problem is.Then comes the sentence I consider the most useful in the whole rule: a fix made during the review is itself a change and goes through the same four stages again. Repeat until a full pass finds nothing new. Only that state counts as clean.
It also states that --no-verify is forbidden: a failing hook gets fixed, not silenced.
A word about the technique at work here. The stages are numbered, each has its own list of what to check, and at the end a mandatory one-word verdict. That is the same output format control as in ordinary prompts: it is much harder for a model to "sort of check" and say "looks fine" when it is required to pick one of three labelled outcomes.
Response style
The rule about how to talk to me. It opens like this:
The user is a human reading the chat, not Claude Code.He does NOT have the source open in parallel and does NOT want to decodecode identifiers, field names or file paths inside an answer.Talk to him like a colleague, not like a code review tool.
Assume the reader is a competent developer who is NOT deep inthis project. They can code, but are probably juggling severalprojects at once and don't carry this one's specifics in their head.Then a list of what is forbidden by default: code snippets, "file:line" citations, field and class names, big tables, ASCII diagrams. All of it is allowed only when I ask directly.
A separate part describes the shape of the final report: done / left to do / what I need from you. And there, an example taken from life:
✗ "Left: our own migration tree with a drift check, image and manifest, wiring in the launch script."
✓ "Left to do: - Describe the database changes as separate migration steps: right now the table is created on the fly and won't exist on a real server. - Build the image and add it to the cluster description, or there is nowhere to deploy it. - Wire the service into the launch script so it comes up with the rest."Three unrelated pieces of work crammed into one line, in words that mean something only to whoever just wrote them. The reader nods without reading, and later it turns out they agreed to something they never understood.
The bad/good pair works better here than any description, and it is precisely few-shot: one shown example replaces a paragraph about self-sufficient phrasing.
Session budget
Spend tokens in proportion to the task's real complexity — the cheapestpath that reliably solves it, not the most thorough one the budgetwould allow. Limits are a guardrail: they show where you would hit a wallor a rate limit so you can stop short, not a budgetthat has to be used up.A GREEN zone does NOT mean "burn freely".The rule then carries a table of task classes: trivial — edit straight away, no thinking, no exploration; small — targeted reads, everything in one thread; medium — one planning pass and high effort only on the hard fork; large — in phases, with a checkpoint between them.
And a separate section on subagents with the arithmetic spelled out: a fan-out of N agents costs as much as N sessions, so spawning them makes sense only for a clear saving. This rule works in tandem with the hook that brings in live limit figures — that one is covered in detail in the hooks article.
When in doubt, search the web
A short rule, seventeen lines, and nearly all of it describes one scenario:
The known failure pattern to avoid: something doesn't work →you apply a fix based on what you "know" → it stilldoesn't work → each new fix digs deeper into a solution builton a wrong assumption.
Therefore in ALL doubtful cases — when something is unclear, non-obvious,behaves differently than you expected, or contradicts your knowledge —ALWAYS search the web before fixing anything further, and look firstat the most recent official documentation.
If even the search gives no answer — STOP and ask the user.Note the structure: the failure first, the requirement second. That is what lets the rule apply to situations it never spells out, because the model understands what it is being insured against.
The capital letters, on the other hand, I would remove today, and the current version of the rule no longer has them: why is explained above, in the section on prompts.
Pull the branch before working
The cost of skipping it is not a merge conflict at the end. It is workbuilt on a base that no longer exists: a bug already fixed by someone else;a review of code that has since changed; a tracker id or a migrationtimestamp already taken; a decision made against a two-week-old file.None of that surfaces until the work is finished.Then three steps: fetch and see how far the branch is behind; fast-forward; read what arrived if it touches your area. Plus a separate section for when the working tree isn't clean.
Stop at architectural forks
Probably the most valuable rule of them all. It opens with a formulation I like:
Some decisions are an edit. Some are a rewrite. This rule is about the second.
When you notice that a piece of work can reasonably be built in more thanone way and the choice is expensive to undo, stop before writing code,study the whole picture and put the fork in front of the developerwith the background and the options laid out.
Choosing silently and moving on is the failure this ruleprevents: its cost does not show up in the diff, it shows up months lateras work that has to be thrown away.Then the signs by which a decision counts as a fork: hard to reverse; spreads beyond one component or team; fixes who owns what and where the trust boundary sits; changes what is visible from outside (a deployed component, a data model, an API contract); touches money, security or privacy. Two signs or more means stop.
And here is the second half of the rule, without which the first one is harmful:
Raising a fork costs the developer real attention. Before you do, check:
— Reversible within a day? → decide yourself.— Has the project already made an equivalent decision? → follow it; a precedent beats a preference.— Would you be content with any of the options? → not a fork, a taste. Choose.— Is it unclear only because you have not looked? → look first. Most "forks" dissolve on reading.
Expect a handful of real forks in a project, not one per task.If you are raising them weekly, the filter is wrong.Without that filter the rule turns into its own opposite: the agent starts asking about everything, the human stops reading the questions and misses the one that mattered.
Symbol navigation
The project has a server wired in that provides go-to-definition, find-references and symbol-level editing. The rule requires using it instead of reading whole files, and its centrepiece is a mapping table:
| Task | Tool | Instead of || Understand a file's API | symbol overview | reading whole file || Find a class or function | symbol search | grep by name || Read one symbol's body | symbol with body | read with offset || Find who calls it | reference search | grep by name || Rename across the project | symbol rename | dozens of edits |Then a section titled "when the standard tools are the right choice". That is the important half: a language server has languages it doesn't understand, and listing them honestly is more useful than demanding the impossible.
Work tracking
The ninth rule is about the tracker: what becomes a task or a bug, what never does, how entries relate to requirements. It is a big one, and I go through it below in its own section, because what's interesting there is the scheme rather than the wording.
Skills are documentation
The main point of this section: skills in my setup are not "plugins for the agent" but the project's documentation. The same documentation that used to go into a wiki nobody opened.
Documentation in a wiki lives apart from the code and slowly drifts away from it. Documentation in the repository is edited in the same pull request as the code, and the executor reads it. Selectively, at that: a skill's body enters the context only when the task matches it. Twenty-six thousand lines of documentation cost one line of the listing per skill until they are needed.
The prefix in the name is the audience. Skills are grouped not by topic but by whose team they address:
.claude/skills/├── req-uc-auth/SKILL.md requirements: authentication cases├── req-personas/SKILL.md requirements: personas├── req-business-rules-core/SKILL.md requirements: business rules├── ba-acceptance-criteria/SKILL.md analysis: how to write criteria├── qa-bug-report/SKILL.md testing: how to file findings├── dev-backend-new-endpoint/SKILL.md development: new endpoint procedure├── dev-tests-backend-unit/SKILL.md development: unit tests└── dev-workflow-git/SKILL.md development: merge conflictsA new role joins the team and a new prefix appears, not a new wiki.
What a skill looks like. Frontmatter with a name and a description, then ordinary markdown:
---name: dev-backend-new-endpointdescription: Procedure for adding an HTTP endpoint: contract, validation, layers, tests, client regeneration. Use when creating a new endpoint or backend module.---
# A new endpoint
1. Describe the contract in `api.md` — before the code, or the two diverge.2. The controller only receives and returns; logic in the service, data access in the repository.3. Input validation is mandatory, errors in the shared format.4. Tests: the happy path, a validation failure, missing permissions.5. Regenerate the frontend client and check that it builds.
## Checklist- [ ] api.md updated before the code- [ ] no logic in the controller- [ ] all three tests in place- [ ] client regenerated, build greenThe description is the most important field: the agent decides from it whether the skill fits the task. "A FastAPI reference" works poorly. "FastAPI architecture and production practices; use when building or reviewing FastAPI services" works well. In the listing the description together with the when_to_use field is cut at 1,536 characters, so put the main use case first.
It is essentially a small routing prompt: it has to carry both the subject and the trigger condition. The skill's body, meanwhile, is kept short, because once loaded it stays in the conversation for the rest of the session and rides along in every following request. And after compaction only the beginning of each invoked skill comes back — the first five thousand tokens, and no more than twenty-five thousand for all skills together — so the most important part goes at the top of the file. The same considerations apply here as in context engineering: a long reference is better split, with the detail moved into neighbouring files the skill points at.
Requirements as skills. A requirements skill looks like a normal analyst's document. Use cases with their own ids, personas, boundaries, acceptance criteria. Nothing "for the agent" about it:
## UC-AUTH-002 Sign in with email and password
**Personas:** PER-001 Agent, PER-002 Manager**Priority:** P0
### Acceptance criteria- AC-UC-AUTH-002-001 — with valid credentials a session opens and works in both applications without signing in again.- AC-UC-AUTH-002-002 — with a wrong password the answer is identical whether or not the account exists (no enumeration hints).- AC-UC-AUTH-002-003 — after five consecutive failures sign-in for that email is blocked for 15 minutes.And here comes the main part: tasks and bugs reference those ids. A tracker entry carries a link rather than a retelling. The requirement's text is copied nowhere and lives in one place. If an entry and a requirement disagree, the requirement document wins.
It cures a familiar disease: a criterion rewritten into a task, into the wiki and into a test case, and three versions of it six months later.
But this is only one of the options
Keeping documentation as skills is my choice, not the one right path. People solve this very differently, and it's worth knowing what the options are.
A plain documentation folder in the repository. The simplest variant: markdown in docs/ plus a line in the project instructions saying where it lives. Nothing to configure, humans read it in GitHub as is. There is exactly one downside, and it is substantial: the agent won't remember it exists until you name a file. It doesn't know what's inside and at best will find something by text search.
AGENTS.md. A cross-tool context file read by Codex, Cursor and a dozen other agents. Claude Code reads it by itself too, but only when the project has neither CLAUDE.md nor CLAUDE.local.md, so even a personal CLAUDE.local.md with your own notes switches it off. When there is a CLAUDE.md, it is what gets read by default, and AGENTS.md is brought in with an @AGENTS.md line inside it or by a setting that tells Claude Code to read both files. A good choice for a team where different people use different agents. The limitation is the same as for project instructions: it is one file and must not swell into a reference manual.
An external wiki over MCP. Confluence, Notion, Linear, whatever: the documentation stays where people already maintain it, and the agent reaches it through an MCP server. The analyst edits a page in the familiar interface, with comments and history, and the agent reads the same thing. You pay with the network, accounts, and the fact that the documentation's version lives apart from the code's: the page changed yesterday while the branch you are fixing matches last month's state.
Obsidian and its kin. A local vault of markdown files that the agent reaches either through an MCP server or by simply being given the directory. The format is the same plain text, so the vault can live in git, and both a human with their link graph and search and the agent work on top of it. People use this as shared memory between tools and sessions: notes, decisions and drafts in one place available to Claude Code and to another agent alike. For a personal knowledge base it is an excellent option. For a team's project documentation it is weaker: the link to the code is lost again, and the vault lives a life of its own.
Documentation platforms with MCP and llms.txt. Modern services like GitBook or Mintlify serve documentation in two shapes at once: a human site and a machine-readable layer, down to an automatically provisioned MCP server. Sensible when the documentation is public and has to be published somewhere anyway.
Search over a large corpus. With thousands of pages of documentation none of the options above fits into the context, and the question moves into retrieval: a vector store, hybrid search, a dedicated server handing the agent the right fragments. That is engineering in its own right, not "put the files in a folder".
What skills win
One property, and it is why I moved to them: the agent always knows they exist. The list of skills with their descriptions enters the context at the start of every session (except those only you can invoke), so the agent pulls the right document itself, unprompted. A documentation folder doesn't work that way: until you name a file, it might as well not be there.
The rest is smaller but pleasant. Documentation is versioned together with the code, so an old branch holds the documentation matching that old code. Edits go through normal pull request review. Nothing needs configuring, everything works offline, without tokens or external services. And the format is open: Claude Code skills follow the Agent Skills standard, which other tools understand too.
What you pay with
The downsides are better listed up front.
The skill list itself occupies context. Not the bodies but the roster of names and descriptions, and it does so every session. That roster has a budget of one percent of the context window. When there are so many skills that it doesn't fit, Claude Code drops the descriptions of the least-used ones, leaving just their names. So you pay less in tokens than in invisibility: without a description the agent won't realize a skill fits the task. /doctor estimates what your list costs, and /skill-doctor shows which skills are hardly ever used.
It is awkward for humans to read. Inside a repository there is no documentation search, no table of contents, no margin comments, no comfortable handling of images. An analyst used to Confluence will not go into GitHub for requirements. In my case that is solved by the requirements being edited by the same person who works with the agent, but in a large team it becomes a problem.
No collaborative editing or discussion. A comment on a paragraph, a discussion inside the document, a "you were mentioned" notification — none of that exists. There is a pull request, which is far more formal.
Several repositories mean several copies. Company-wide practices then have to be duplicated, or linked with symlinks, or packaged into a plugin. In a monorepo there is no problem; across five repositories it is noticeable.
The temptation to dump everything in. Skills are cheap, so it is easy to throw a hundred files in and end up with the same dead wiki, only in git. The one safeguard is the description the agent picks a skill by. Written carelessly, the document will never be pulled in, and you won't even find out.
No role filtering. A developer sees the analyst's skills and vice versa, and everyone pays for them in context. More on that below, in the section about roles.
If it comes down to one rule: what the agent needs while working on the code is better kept next to the code; what people need for discussion and planning is better kept where people are used to working. My boundary runs roughly like this: requirements and practices as skills, while plans, deadlines and correspondence stay in the external system.
What it costs
Project instructions and rules load into every session in full. In my case, in August, that came to 571 lines of instructions plus 1245 lines of rules. Almost two thousand lines before you have typed your first word.
Noticeably more than recommended, and I pay for it in context. A deliberate trade: predictability in a project with several applications and shared infrastructure is worth more than the saved tokens. But the trade has a limit. If the file kept growing, I would scatter the rules across path patterns.
By the way, if the agent keeps violating some rule, the cause is almost always volume rather than wording. The rule got lost. Cured by shortening, not by adding capital letters. And if a rule must have no exceptions at all, it belongs not in text but in a hook or a deny rule.
Three months later
The "predictability is worth more than tokens" trade had to be reconsidered. By the end of August the instructions file had grown to 653 lines and was cut to 216, and at the start of October the project went through a full clean-up. Since then the instructions hold about a hundred and fifty lines, and there are thirty-six skills instead of a hundred and two: seventy-two were removed, and six new ones were added along the way.
What changed:
- Seventy-two generic skills. References like FastAPI best practices or Python performance. The model knows all of that without us, and we were paying for them with a place in the listing of every session. What stayed are the requirements, twenty-four skills, and procedures that exist only in this project, such as reviewing a pull request by the team's rules.
- Notes on parts of the project were gathered into separate CLAUDE.md files in the backend, frontend, infrastructure and other folders. Such a file is loaded only when the agent starts working in its folder.
- The
.claudeignorefiles. Claude Code doesn't read them: the only way to close a file off from the agent is a read deny rule in the permission settings. - Three rules — no commits unless asked, the pre-commit review and pulling the branch — became two: "before starting work" and "finishing work", which covers reviewing the changes, committing only on request and taking a pull request to green checks. A finished task is checked once by a separate reviewer subagent.
New rules arrived on code quality, on merge conflicts and on working autonomously: look things up yourself before asking, and carry a task to the end instead of handing it back halfway. There are eleven rules in all now, plus the API reference, about eleven hundred lines, and every one except response style has been rewritten from scratch. The quotes above are from the August versions: as examples of wording they still hold.
The conclusion matched the one Anthropic itself arrived at: write down for the agent only what it won't find in the code by itself. How to write a good backend in general the model already knows; how things are done in your team, it doesn't.
Documentation: how and where
The principle is simple. All documentation the agent reads lives in instructions, rules and skills. There is no "docs for the agent" folder at all, so that there are never two sources of truth. That is one project's decision, not the only possible one: I went through the alternatives and their price above.
What follows from it:
Rules and skills are the source of truth. The agent is explicitly forbidden from inventing behaviour that contradicts them. If it thinks a document is wrong, it says so to a human rather than acting on its own.
Don't edit the documentation unasked. It seems odd at first and turns out to be necessary: an agent that trips over an inconvenient rule will happily bring the rule into line with its own behaviour.
Something new gets a new document; a change to something existing edits the existing one. Otherwise in six months the project holds two skills about the same thing with different versions of the truth.
One template. There is a dedicated skill about how to write rules and skills: structure, phrasing, delimiters, a mandatory checklist at the end. The checklist turns a description into a verifiable requirement and gives the agent a way to check whether it followed the document.
That skill is essentially a body of prompt-engineering techniques applied to a project's configuration, and the rule requires using it whenever any rule or skill is created or edited. It sounds bureaucratic and it pays off: documents written to one template contradict each other less often and are followed better. The techniques themselves are covered in the article on prompt engineering.
README for humans, instructions for the agent. Both are needed, but the readers differ. The README explains to a newcomer what goes on here; the agent relies on instructions, rules and skills. When the project structure changes, both are updated, or the developer and the agent end up living in different pictures of the repository.
Technical references separately. Deployment, migrations and load test results live in an ordinary documentation folder at the root. The agent doesn't need them while working on code; a human needs them occasionally.
A task and bug tracker right in the repository
The most idiosyncratic part of my setup.
Tasks and bugs live in the repository as plain markdown files, one file per entry. No database, no web interface, no CI checks. The script does two things: create an entry and rebuild the index. Automation ends there.
management/├── tasks/│ ├── auth/TASK-001-one-password-for-both-apps.md│ ├── billing/TASK-037-invoice-pdf-export.md│ ├── done/TASK-012-import-legacy-contacts.md│ ├── INDEX-AUGUST-2026.md│ └── TEMPLATE.md├── bugs/│ ├── auth/BUG-003-sign-in-loops-on-expired-token.md│ ├── done/BUG-001-avatar-upload-fails-over-2mb.md│ └── INDEX-AUGUST-2026.md├── decisions/ADR-0001-where-user-sessions-are-stored.md├── logs/roman/2026-08-06/a1b2c3d4.log└── new.pyWhat this gives you. The agent sees the whole task without leaving the project, together with the requirement it references and the code it edits; the entry lives in the same history as the code, so it is always visible which commit closed it and what changed along the way. Two people (or two agents) working on different entries physically never edit the same file, so merge conflicts cannot happen by construction — probably the strongest argument against the one big task-list file everyone is used to. Plus everything works offline, without accounts or tokens.
What an entry looks like
Here is the real bug template, only with invented content:
---id: BUG-003title: 'Sign-in loops on an expired token'severity: P1status: CONFIRMEDmodule: autharea: 'sign-in / refresh token'found: 2026-08-04closed:assignee: ''req: 'AC-UC-AUTH-002-001'source: 'QA wave 12'---
# BUG-003 — Sign-in loops on an expired token
- **Steps:** open the app with a token older than 24h → sign-in screen → enter valid credentials → back to the sign-in screen.- **Expected:** AC-UC-AUTH-002-001 — a valid sign-in opens a session.- **Actual:** the refresh call returns 401 and the client retries forever.- **Log:** - 2026-08-04 — filed from the QA wave. - 2026-08-05 — reproduced on staging, confirmed. Refresh interceptor does not clear the stale token before retrying.
## Screenshots
- 2026-08-04 — `BUG-003_04-AUGUST-2026_11-20_loop.png` — the loop, three redirects in the network tab.An entry is created by a command, not by copying a file by hand:
python management/new.py bug --module=auth --severity=P1 \ --title="Sign-in loops on an expired token"
python management/new.py task --module=auth --priority=P1 \ --title="One password for both apps"
python management/new.py attach BUG-003 shot.png --note="the loop after the fix"The script allocates the next free number, puts the file into the module folder and rebuilds the month's index. The index looks like this:
# Task index — AUGUST 2026
**Entries:** 31 · **Open:** 30 · **Closed:** 1
| ID | Prio | Status | Batch | Module | Title || --- | --- | --- | --- | --- | --- || TASK-029 | P1 | IN_PROGRESS | 2026-08-04-export | billing | Export invoices as PDF from the admin panel || TASK-030 | P1 | TODO | PROJ-42 | platform | Choose a feature-flag library || TASK-031 | P1 | TODO | PROJ-42 | platform | Set up CI/CD for the staging environment |Details that matter in practice:
Ids are permanent. They are never reused and never renumbered: commits, correspondence and other entries reference them. The running counter, admittedly, later had to give way to random four-character codes like BUG-2W7F: two people on two branches took the same "next free number", and git merged both entries without a murmur, since their file names differ. Older entries kept their numbers.
Folders are named after requirements. The area an entry belongs to is named after the requirements file that owns it: req-uc-auth → the auth folder. Tasks and bugs share the same folders. A small thing, but it removes the eternal "where does this go" argument and connects the tracker with the documentation.
Closing through git mv. The status changes, a date is set, a line is appended to the log, the file moves into the closed folder. Git stores no moves: git mv gives the same result as a plain move, and git log --follow traces the file by the similarity of its content. So an entry's history breaks only if the move comes with a large rewrite of the file, and that is the thing to avoid in a closing commit.
Screenshots in the repository. A separate command puts the image into the attachments folder, names it by a scheme and appends a line to the entry. Images only, up to four megabytes, cropped: git keeps every byte forever. Video goes in as a link. The screenshots section is append-only, because a bug that lived for three weeks carries a shot per state, and the old lines have to show how it was then.
The language is English in Latin script. The file name is built from the title, and the tracker is read by people with no shared mother tongue. A description may stay in the language the report arrived in if asked, but the title and the metadata are always Latin.
What never goes into the tracker
The most important rule of the whole scheme, and it goes against habit: the tracker holds the product and nothing else.
There is exactly one test. Does it run at the customer's side? The applications, the libraries they are built from, the data, the infrastructure — yes, that is the product.
Everything that exists only to make building the product easier for us doesn't enter the tracker at all. Not as a task, not as a bug, regardless of how much work it was or who asked. The repository's documentation, rules, skills, the tracker itself and its script, hooks, service scripts, CI configuration, moving folders around. That work is simply done, and the record is the commit plus the automatic session log.
The wording in the rule is harsh, deliberately so:
No entry at all — however broken it looks and however much workit cost: a stale document, a dead link, a wrong path in a rule,a defect in this very tracker or in a service script, a hook misreadingits own input, a broken CI setting, a renamed folder, a rulesomebody asked for. None of it reaches the customer,so none of it is a bug. And turning it into a task is the same mistakeunder a different label. Don't file it. Do the work, the commit speaks for it.The temptation is strong: there is a lot of work and you want it visible. But a tracker stuffed with housekeeping is one nobody reads, and reading is exactly what it was created for.
The second split is tasks versus bugs. Anything QA finds is a bug, and only a bug. Fixing a bug does not create a task. A task is new functionality, or rework of existing functionality, that somebody asked for.
Decisions
Next to the tasks live architectural decisions, one file per decision. The format is the familiar ADR one:
---id: ADR-0001title: Where user sessions are stored: database or cachestatus: Proposeddate: 2026-07-31deciders: Engineering lead / Architectrelated: - management/tasks/auth/TASK-001, TASK-002 - Requirements BR-SEC-004 (one session shared by both apps)supersedes: none---
## Context what forced the decision and which question is blocked## Decision numbered points: what exactly was decided## Verified facts (checked in code, not assumed) a "fact → where in code" table## Consequences what this makes easier and what we pay for it## Alternatives what was considered and why it was rejectedThe verified-facts section came about after one decision was made on somebody's retelling and the code turned out to say otherwise. Now every fact in an ADR carries a reference to the place in the code it came from.
The point is simple: an argument settled once doesn't resurface every two months.
The session log that writes itself
The third part of the tracking, and nobody maintains it by hand. A hook records everything that happened in the session: your prompts, the agent's questions and what you picked, per-turn statistics, changed files with line counts, the final report. A file per session, a folder per day, a folder per developer.
It looks like this:
session start: source=startup · model=claude-opus-5
════════════════════════════════════════════════════════════
prompt:fix the infinite redirect on an expired token, BUG-003
turn: model=claude-opus-5 · effort=high · 4m 12s · tools=23 (Read 9, Grep 5, Edit 3, Bash 6) · subagents=1
files: ~ apps/web/src/api/interceptors.ts +14/-6 +[41-48,52-57] -[41-46] ~ apps/web/tests/auth.spec.ts +31/-0 +[88-118]
answer:The cause was the interceptor retrying the request with the stale token...
subagent done: general-purposesession end: reason=prompt_input_exit · duration=51mWhy, when the agent is right there? Because asking it what happened in the session is a bad idea. By the end of long work its context is already compacted: some details are gone, others recounted optimistically. A mechanical record made by something other than the model is the only honest answer to "what actually happened".
Forty-seven such files had piled up by August; by November there are more than seven hundred. I opened them more often than expected: usually to work out when and why a strange piece of code appeared. It is also the answer to "so where is the work on the repository itself tracked, the work that must never become a task". Right here. Automatically, without a single line of manual bookkeeping.
What the scheme doesn't have
Honestly about the limits. There is no board, no notifications, no sprint reports, no time tracking. If management lives in Jira, this scheme doesn't replace it: in my case the grouping label holds a Jira key.
The division comes out like this. In the external system, planning and reporting for a manager. In the repository, what the executor needs while working, together with the code and the requirements.
What's missing: roles
Since I've grouped skills by prefix for different teams, let me also say what the tool itself lacks for that scheme.
The prefix in the name is a convention, not a mechanism. The analyst, the tester and the developer work in one repository and get one and the same configuration: identical instructions, the full set of skills, identical write permissions.
Three annoyances, all three of which I've seen for real. The analyst asks for a spec-versus-code comparison, and the agent, loaded with developer instructions, starts editing the sources. The tester asks to reproduce a defect, the shared instructions say "apply the migrations before testing", and the agent dutifully applies them to a shared environment. And, quieter but dearer: everybody pays context for every skill, including the ones their work never touches.
The workaround is obvious and poor: everyone keeps a personal configuration in their home folder. It isn't in the repository, nobody reviews it, and a newcomer simply doesn't have it.
The right answer is to make a role a full configuration layer that lives in the repository. Its own share of the instructions, its own set of skills and agents, its own permissions and, crucially, its own writable scope that edits cannot leave:
.claude/├── CLAUDE.md the shared part for everyone├── settings.json├── skills/└── roles/ ├── dev/{CLAUDE.md, settings.json, skills/, agents/} ├── qa/{CLAUDE.md, settings.json} no migrations, no deploys └── ba/{CLAUDE.md, settings.json} writes only to docs/ and specs/And it has to be a prohibition at the tool level, not a request in the text. Exactly the same difference as between a rule and a hook.
Part of the scheme can already be assembled from what exists. --agent gives a session the tools and model of a chosen subagent, and a settings file passed with --settings adds deny rules and, through skillOverrides, hides other teams' skills from the agent or leaves just their names. But all of it is picked by hand at launch rather than sitting in the repository as a ready-made role.
I filed this as a feature request for roles in Claude Code: with the problem described, what the --agent and --settings flags already cover, and what is still missing. The full version, with the merge semantics for settings (a role can only narrow the project's permissions, never widen them), is in the first request, which an inactivity bot has closed. If the pain is familiar, go and support it — the more confirmations, the better the chance somebody gets to it.
Subagents
A subagent is a separate session with its own context, its own tools and its own system prompt. It does part of the work and returns the result. There is also a fork: it doesn't start from a blank slate but inherits the whole current conversation.
The benefit isn't that a subagent is smarter: by default it's the same model or a simpler one, and it won't solve the same task any better than the main session. The benefit lies in four things. Parallelism: independent pieces of work run at the same time. Noisy output — a full test run, a wide search through the code — stays with the subagent instead of riding along in every later request of the main session. Fresh eyes for review. And trimmed permissions: a reviewer that can read but cannot edit, with the restriction held by the tool itself.
Most of the time you don't even have to ask: Claude Code hands broad code searches to the built-in Explore subagent and side tasks to forks on its own, and runs them in the background so the main conversation doesn't stall.
A subagent of your own is described in one file:
---name: security-reviewerdescription: Reviews changes for vulnerabilities. Run before a release and on edits to authentication, file uploads or database access.tools: Read, Grep, Glob, Bashmodel: opus---
You are a senior security engineer. Review the changes for:- injections (SQL, XSS, shell commands);- authentication and authorization flaws;- secrets in the code;- unsafe handling of user data.
Point at specific lines and suggest a fix. Leave style alone.The body of that file is another model's system prompt, not a note to self. Everything applies as usual: an assigned role, explicit boundaries ("leave style alone"), an output format and a trigger condition in the description. On writing prompts for agents and tool use there is a separate section in the prompt article.
Another use is independent review. Whoever wrote the code is a poor reviewer: they see their intentions rather than the diff. It is worth asking a subagent specifically:
Use a subagent to review the changes against PLAN.md. Check that everyrequirement is implemented, that the listed edge cases have tests andthat nothing outside the task changed. Report gaps, not style preferences.A caveat worth knowing in advance: a reviewer asked to find shortcomings will find them. Even when the work is sound, because that is what it was asked for. Chasing every remark leads straight to extra abstraction layers and tests for impossible cases.
And about money. Subagents aren't free: each sends its own requests, and they count against the same limits as the main conversation. A fresh subagent also has to gather context the main session already had, so it sometimes ends up even slower. A fan-out of ten costs roughly as much as ten sessions. Where you can save is the model: simple work, like collecting the files that import a module, goes to a subagent on Haiku, with a model: haiku line in its definition. An edit in one or two files is always faster in the main session.
A separate story is several parallel sessions. The easiest way is to separate them with git worktrees: each gets its own directory and its own branch, and edits don't collide. claude -w name starts a session straight in a new worktree, and gitignored files like .env, which a fresh worktree lacks, Claude Code copies by itself if you list them in a .worktreeinclude at the repository root. The "one writes, another reviews" scheme works for the same reason as the reviewer subagent: a fresh context isn't infected by the author's reasoning.
Context in practice
Techniques I use constantly:
The first minute. Watch where the agent is heading and press Esc the moment it drifts: it stops, keeping everything done so far, and you can correct course.
A new task means a clean context. Clearing between unrelated tasks is cheaper than any optimization. The tail of somebody else's task is both extra tokens and extra distractions. /clear costs nothing, and with a name, /clear oauth, it also labels the session so you can come back to it later.
Two failed attempts mean stop. Corrected twice and it's still wrong? The problem is no longer the wording: the context is stuffed with failed approaches. A clean session with a more precise brief nearly always beats a long one with accumulated corrections.
Compaction is configurable. Before the window fills up, the history is compacted automatically. You can also compact by hand, with an emphasis (/compact keep the API changes and the test commands), and state in the project instructions what must survive:
When compacting, always preserve: the list of changed files,the test commands, and the architectural decisions with their reasons.Just remember that compacting a long session is a big request in itself: the model re-reads the whole conversation to summarize it. If you don't need the history, /clear is cheaper.
Rewind instead of caution. Every prompt of yours is a restore point: /rewind, or Esc twice on an empty prompt, and you can bring back the conversation, the files or both. That changes how you work: instead of agonizing over a risky step, try it and roll back. Just remember that rewind is not git: it only knows about files the agent edited with its own tools in the main conversation, and changes made through the command line aren't tracked.
A quick question on the side. For trivia like "what does this flag do" there is /btw: the answer never enters the history.
The status line and /usage. The size of the context and the spending deserve to stay in front of your eyes: in the status line, all the time. And on a subscription /usage breaks the spending down by skills, subagents, plugins and MCP servers and suggests what to change.
Permissions
There are several permission modes, and the default is no longer the strictest one. Interactive terminal and VS Code sessions start in auto mode: a separate classifier model looks at each action before it runs and stops what you would stop yourself — curl | bash, production deploys and migrations, a force push over someone else's work, sensitive data sent outside, actions that look driven by text the agent read rather than by you. After three blocks in a row, or twenty in total, the mode gives up and goes back to asking a human. When a non-interactive claude -p run uses auto mode, there is nobody to ask: a blocked action simply doesn't run, and Claude carries on without it.
At the other end is manual mode, where you confirm every edit and every command except reads. Safe and unbearable: by the tenth confirmation you aren't reading, you're clicking. And the mode with no checks at all, bypassPermissions, only makes sense in a disposable container. Shift+Tab cycles through the modes, planning included.
Auto mode is a model's judgment, not a rule, and it can be wrong. So everything in the "never" category is written down in a form the tool itself enforces: deny rules in the settings, and hooks. Deny rules and PreToolUse hooks hold in every mode, auto and bypassPermissions included, and fire before the classifier even sees the action:
{ "permissions": { "allow": [ "Bash(npm run test *)", "Bash(npm run lint)", "Bash(npm run build)" ], "ask": ["Bash(git push *)"], "deny": [ "Read(.env)", "Read(.secrets/**)" ] }}Written without ./, these rules catch such a file at any depth under the directory Claude Code was started in; Read(./.env) would protect only the one right there. The deny rule on reading .env covers both the read tool and cat .env on the command line: Claude Code recognizes the common file-reading commands. A script that opens the file itself it won't catch. Allowing reads inside the project, or commands like git status and git diff, is unnecessary: they need no confirmation anyway. A space before the asterisk is the current notation; the old test:* form still works, but the permission dialog writes the new one. The full rule syntax is in the commands and settings reference.
If the classifier keeps stopping something that is routine for you, don't approve it by hand each time: describe your environment in plain words in your personal settings — which domains are yours, which environment may be touched. In manual mode the reverse helps: /fewer-permission-prompts scans past sessions and adds common safe commands to the allowlist.
The strictest option is the sandbox (/sandbox, on macOS, Linux and WSL2): OS-level limits on the filesystem and network for the commands the agent runs. It picks up your read deny rules as well, so for anything security-related you want both layers.
Whatever you choose, one rule stands. Read the full diff before a commit. It mattered before agents and matters more now: the model happily edits things nobody asked about and tidies up a neighbouring file while it's there.
When nobody is watching
Everything above matters twice as much when the agent works without you. While you're watching, a missing piece of context is no big deal: you'll notice within a message or two. Start a task before going to bed, and in the morning you find out it spent the whole night building on a wrong assumption.
Before such a run it's worth going through five questions, for that specific task:
- Does the agent know what done looks like? A goal condition, a spec file, a failing test it has to turn green.
- Can it check itself? Tests, a
Stophook, a review step. - What may it touch? Permission rules, the sandbox, a separate worktree, the one branch it may push to.
- What stops it?
--max-turns,--max-budget-usd, a spend limit. - Where does the result go, and who accepts it? A pull request or a report — and a person who approves the merge.
The run itself is claude -p "task" in a script or in CI. With --permission-mode dontAsk, anything not allowed in advance through --allowedTools is refused rather than left hanging for an answer. Repeating a task on a timer inside an open session is what /loop does, and /schedule sets up a cloud task on a schedule that runs even with the laptop closed. Start with three files, not three hundred: see what went wrong, fix the prompt, then run the rest.
Models, effort and money
An agent's work consists of steps of wildly different difficulty. Understand the task, find the files, apply an edit, check the result. There is no point keeping the most expensive model on every step.
The practice is this: the main session on a strong model, mechanical work delegated to subagents on a simpler one, the effort level raised only where there is a hard fork. Both skills and subagents can set the model and effort for themselves, so the routing can be described once:
---name: dev-changelogdescription: Build a changelog from the commit history between two tags.model: haikueffort: lowdisable-model-invocation: true---A caveat for skills: without context: fork, a skill's model applies to the main conversation for the rest of the turn. The cheaper model then gets the whole history, and the prompt cache of the main model does not apply to it, so in a long session the saving can turn into a loss. With context: fork the skill runs in a subagent of its own and sees only its instructions.
The main control over how much the model thinks is the effort level: low, medium, high, xhigh and max, switched with /effort. Opus 5.5, Sonnet 5.5 and Haiku 5.5 default to medium, which is enough for everyday work with clear boundaries; the other models with effort levels default to high, and Opus 4.7 to xhigh. Raise it when getting it right depends on cases that are easy to overlook: a bug in someone else's code, a flaky test, a schema change where every reader of the old shape has to be found. max is for a hard problem the agent works through without you; on an ordinary task it overthinks, and you pay for an answer no better than high would have given. Phrases like "think hard" in a prompt are ordinary text and don't raise the effort level. And for one tricky question in the middle of routine work there is the word ultrathink: it asks for deeper thinking on that turn only.
Subscription limits are a topic of their own. By default the agent doesn't see them, so it cannot size its spending: it fans out subagents just as happily when the reset is four hours away as when the budget is nearly gone. A human sees them in /usage, scripted runs have hard caps in --max-turns and --max-budget-usd, and in my case it's solved by a hook that brings live numbers into the context and forbids fan-outs in a hot zone. Details in the hooks article.
MCP and command-line tools
Two ways to give the agent access to the outside world.
Command-line tools are the most context-efficient path. If a service has a CLI, the agent uses it perfectly well: files tasks, reads comments, looks at logs, brings up an environment. It picks up unfamiliar utilities too, if you ask it to work them out from the built-in help.
MCP servers are for structured access: a database, a tracker, designs, monitoring. The same category holds servers for working with the code itself: symbol navigation instead of reading whole files saves a great deal on large repositories. For typed languages Claude Code also has official code intelligence plugins built on language servers: go-to-definition instead of grep followed by reading several candidate files, and type errors right after an edit, without running the compiler.
A tip from practice: connect only what you actually use. Full MCP tool descriptions are now loaded on demand, but the tool names and the server's instructions sit in every session's context and ride along in every request, so a dozen servers kept "just in case" costs more than it seems. Switch off the ones you don't need in /mcp.
Advice that has aged
Models have improved noticeably, and some advice that was right not long ago now gets in the way. If any of it is still in your habits or your instructions, feel free to drop it:
- "Context is the main constraint." A million-token window and automatic compaction have made hitting the wall rare. Clearing the context between tasks is still worth it, but for cost and focus.
- "Hand work to subagents to save context." Subagents are good for parallel work, noisy output and independent review, and every one of them costs tokens.
- "A subagent will give a better answer." The same model on the same task doesn't get smarter. A reviewer's fresh eyes help, but that's a different thing.
- "Think hard" in the prompt. Depth is governed by the effort level, and those words are ordinary text. Only
ultrathinkworks, and for one turn only. - IMPORTANT and capital letters. Current models respond by applying the rule too broadly. If a line doesn't hold, the file is too long or it's a job for a hook.
- "Don't be lazy, keep going until it's done." Models carry an agreed task through on their own, and lines like that are more likely to cause extra work. Giving a check that has to pass is another matter, and still useful.
- Describing the architecture and folder layout in the instructions. The agent reads the repository itself. Write down only what isn't in it.
What stayed true from the Cursor practices
Some advice from the old article hasn't gone anywhere. It is about working with a model in general.
Decompose and control the steps. A "build it all" request produces code that doesn't work the way you expected, and untangling it costs more than writing it would have. Steps must be self-sufficient: after each one the project builds.
Log generously. A console overloaded with logs hinders a human and helps the agent: matching output against code, it pins down what broke far more precisely.
Ask for current library versions and watch the licences. The model will insert the version it saw most often in training, and that is rarely the latest: training data lags behind the model's release by months, and frequency of mention pulls towards even older versions. It doesn't look at licences at all, and dragging a copyleft library into a closed project is easy.
Settle on the approach in advance. One thing can be done in five ways, and without a decision the model picks — based on what appeared most often in its training data. Ask about the options and their downsides before the code is written.
Different tasks, different sessions. The advice about a new chat per task carried over unchanged, only now it has a precise explanation: it is about the cost and focus of the context.
How to ruin it all
I've collected the ways I see most often. Including in my own work.
The junk session. Started with one task, asked about another, went back to the first. The context is stuffed with everything at once.
Endless corrections. The agent did the wrong thing, you corrected it, still wrong. After two rounds it is cheaper to start over.
Bloated instructions. The file grew and half of its directions stopped working: the important part got lost. Cured by ruthless trimming.
Trust without verification. A plausible implementation that doesn't cover the edge cases. Nothing to check it with — don't ship it.
Endless exploration. "Work out how everything here fits together" with no boundaries, and the session has paid for two hundred files read. Claude Code hands a broad search to a subagent by itself, but the boundaries are yours to set: scope the investigation.
In short
If you take one thing from this article: set up the environment first, then ask for code. Only set up what the agent can't see by itself: the rest it will read in the code.
A check the agent can run itself. Short project instructions holding only what it won't find in the code. Rules for mandatory behaviour, skills for knowledge on demand, hooks and deny rules for what must always or never happen. Task tracking next to the code. A deliberate attitude to context — for the sake of cost and focus.
The work is one-off and pays off every session. And the difference between "the agent constantly does the wrong thing" and "the agent does what's needed" usually lives here, not in the model and not in the phrasing of the latest request.
And once more about where I started: all of this is prompts. Instructions, rules, skills, subagent descriptions. Written carelessly, they give exactly the result careless prompts give, except you pay for it every session rather than once. The techniques that work here are covered in the article on prompt engineering.
On hooks — the mechanism that makes the agent's behaviour deterministic — there is a separate article with every event and three working examples.