How I Use Claude Code: A System, Not a Chat Window

The reliability is not in the model. It is in the system around it.

Last week I pointed Claude Code at my dotfiles repository and asked it to make sure nothing private would leak before I made the repo public. It read every one of the 193 tracked files in full. Not grep, not sampling: complete reads, split between the main session and three reviewer agents running in parallel. The audit came back with exactly one real finding: a client's name sitting inside an HTML comment as example placeholder text, in a file I had not opened in months.

Then it moved 78 editor configuration files into my private repository, rewrote the public repo's single-commit history so those files never existed in it, and force-pushed. The push ran behind a guard it wrote itself: a few lines of shell that counted leftover sensitive files and refused to push unless the count was zero.

None of this happened because the model is clever. Models are clever everywhere and reliable almost nowhere. It happened because the session ran inside a system I have been building for months: written standards, packaged workflows, human gates around anything irreversible, verification before every claim, and a memory that outlives the session. This article is a tour of that system, with the real episodes that shaped it.

Write your standards down once

My global CLAUDE.md, the instruction file Claude Code loads into every session, opens with this line:

"Do not tell me I am right all the time. Be critical. We're equals."

That sentence does more work than any prompt trick I know. The default failure mode of AI assistants is agreement: you propose something mediocre, the model congratulates you and builds it. Making skepticism a standing rule turns the assistant into a colleague who pushes back, and it costs nothing ongoing, because it is simply always there.

That is the pattern behind everything else in this article: if you catch yourself telling the agent something twice, write it down once instead.

The constitution stays deliberately thin. Detailed standards live in per-language rule files (php.md, javascript.md, rust.md, git.md and a few others) that the constitution only points to, and the agent loads a rule file when the task matches it. A Rust question never pays the token cost of my Laravel conventions. The same progressive disclosure pattern repeats inside each project: the project's CLAUDE.md holds a thin capability table that points into spec files, where the real contract detail lives. Context windows are large now, but they are not free, and an agent whose context is stuffed with irrelevant rules is measurably worse at applying the rules that matter.

Two details people miss. First, rules are not only about code style. My rule files also carry machine knowledge: how local domains are served, where databases live, how git worktrees map to URLs. That is how the agent, later in this article, will know how to spin up and browser-test an isolated copy of an app without being told. Second, there is a discipline about where knowledge lands: anything durable and shareable goes into the versioned constitution or specs. The agent's private memory is only for what does not belong in the repo.

Here is one real rule, shortened:

When a conclusion depends on whether something is present or absent,
read the command's full output before asserting. Do not pipe a status
command through tail, head, or a narrow grep and then conclude
something is missing.

And yes, the constitution also bans em dashes and emojis in everything the agent writes. The em dash is the most recognizable tell of AI-generated text, and the ban forces plainer sentences. This article obeys the same rules.

The payoff is invisible, which is the point. Every session, in every project, starts already knowing how I work. I have not explained my formatting preferences, my git etiquette, or my testing conventions to the model in months.

Package repeated work as skills

Standards cover how the agent behaves. Skills cover what it knows how to do. A skill in Claude Code is a markdown file with a description of when it applies and a procedure to follow; the agent loads it when a task matches the description. Think of it as a runbook the agent can actually execute.

Mine include a server audit that walks a production fleet over SSH (nginx, PHP-FPM, MySQL, Redis, backups, security posture), a merge request review that checks out the branch and reads whole files rather than diff hunks, a bug diagnosis loop, an incident investigation playbook, and a skill called grilling whose only job is to interrogate a plan until it cracks. Each one started life as a task I noticed myself explaining for the second time. The frontmatter is the whole trigger mechanism; this is the real header of my MR review skill:

---
description: "Review a GitLab MR or GitHub PR by checking out the"
  branch and reading full file contents. Can also post the review
  back inline (file:line discussions) when the user asks.
user-invocable: true
---

I did not write all of my skills. Community packs install from public plugin marketplaces the same way editor plugins do; one pack alone (superpowers: github.com/obra/superpowers) supplies brainstorming, test-driven development, systematic debugging, and a verification discipline that demands evidence before any claim of success. If you are starting today, install before you build.

One preference that surprises people: where a CLI tool and an MCP server both exist, I take the CLI. MCP is the protocol for wiring external tools directly into the agent, and it is genuinely useful, but a server's tool schemas occupy context in every session whether you use them or not. A CLI costs tokens only in the moment it is invoked, and it is easier to permission-scope. So gh and glab instead of a GitHub server, a browser automation CLI instead of a browser server. Speed and token budget both win.

The skill I use most is also the smallest. later is a tiny shell command that parks a follow-up note into the current project's notes file. The whole storage mechanism is three lines from its add path:

local file="$PWD/$NOTES_FILE_NAME"
[ -f "$file" ] || printf '%s\n\n' "$NOTE_HEADING" > "$file"
printf -- '- [ ] %s\n' "$note" >> "$file"

While the agent is mid-task in one terminal, I type later "check the failing seeder" in another, and nothing gets interrupted. A Stop hook, a script Claude Code runs when a session goes idle, watches the queue and resurfaces it once things have settled. Follow-ups stop living in my head, and capturing them stops derailing running work.

Gate the irreversible

Everything so far is territory where the agent can act freely. The next layer is about the things it must never do freely: changing behavior contracts, touching git history, shipping code.

Non-trivial changes go through OpenSpec (github.com/Fission-AI/OpenSpec), a spec-driven workflow where specifications are versioned files in the repository and every behavior change starts as a proposed delta against them. I run it with a custom schema that extends the stock artifact set (proposal, design, tasks, spec deltas) with a summary artifact.

A new feature runs through seven steps:

1. Brainstorm. A brainstorming skill interviews me, one question at a time, until intent, constraints, and success criteria are explicit.
2. Grill. The grilling skill attacks the design adversarially: edge cases, race conditions, wrong assumptions. Plans that survive get built.
3. Propose. The agent generates the proposal, design, tasks, and spec deltas. I review, then commit.
4. Apply. The agent implements the tasks. I review, then commit.
5. Push, open a pull request, and let PR-Agent (github.com/The-PR-Agent/pr-agent), an automated reviewer running a different model family, review it. You do not review your own pull request either.
6. Fix what the review finds, and cycle with step five until it comes back clean.
7. Archive. The spec deltas fold into the canonical specs, then commit and push. The pull request is now ready for the final human gate: review and merge.

Two things make this more than ceremony. First, every phase boundary is a human gate and a commit: the agent generates a proposal and stops, implements and stops. It never grants itself permission to continue, because a review point you can skip is not a review point. Second, the different-model review in step five is deliberate redundancy of perspective, not paranoia. Models trained differently have different blind spots; the reviewer catches what the author model cannot see.

Underneath all of it sit the git rules: the agent never creates branches, never commits, never pushes, and above all never force-pushes without being asked. When it rewrote my dotfiles history during the audit, it asked exactly two questions first (amend and force-push? untrack the files from the second repo too?), and the push itself ran behind this guard:

if [ "$leftover" -eq 0 ] && [ "$leak" -eq 0 ]; then
  git push --force-with-lease origin main
else
  echo "ABORT: guard failed; nothing pushed."
fi

Those two variables counted leftover private files and the leaked client name in the tree about to be pushed. If either count had been nonzero, nothing would have moved. Trust the model, but wire the trust to an if statement.

Secrets on a need-to-know basis

The audit that opens this article could safely read every tracked file because there was nothing secret to find. That is not luck. It is architecture.

The public repo's gitignore denies by default: its first rule ignores every path, and each tracked file is re-included by name. A new file, whatever it is (a token, a session dump, an editor state file), physically cannot enter version control by accident; it has to be allowlisted deliberately. Machine and client specifics live in a second, private repository whose link script symlinks them into place. The public repo carries no trace of them, not even the symlinks.

Runtime secrets follow the same least-privilege logic through 1Password. The agent's op CLI authenticates as a service account whose token grants access to exactly one vault, created for agents; my personal vaults are invisible to it. Placing a secret into that vault is a deliberate act, like handing over a single key instead of the keyring. When the agent needs a credential, it fetches it at runtime with op read, so the value passes through process environment and never lands in a committed file or in the session's default context.

None of this is exotic. It is the discipline you already apply to a CI runner, applied to a new kind of colleague: very capable, no concept of discretion. Give it exactly what it needs, and even a full-repo read cannot leak what was never there.

Fan out, verify, and test for real

One agent reading 193 files serially is slow and, worse, fills its own context with noise. So the audit split the work: three subagents (independent agent sessions the main one can spawn and coordinate) each took a slice of the tree and read their files completely, while the main session kept the sensitive, judgment-heavy files for itself: shell init files, git credentials configuration, tool settings. The subagents reported findings; the main session verified them.

Fan-out is not only for reading. Some of my subagents are specialists with their own instructions: a Laravel debugger, a feature builder, a code simplifier. A specialist with a narrow brief and a clean context regularly beats a generalist dragging the whole session behind it.

The other half of this principle is verification, and it goes beyond running the test suite. My environment gives the agent a way to test like a human would. The worktree command spins up a git worktree (a second working copy of the repo on its own branch), and my local web server serves every worktree instantly at its own domain: create a worktree called payment-refactor for a Laravel app called shop, and https://payment-refactor.shop.test is live, no configuration edits, thanks to a wildcard virtual host (the Apache setup lives in my ubuntu-configuration repo). Provisioning hooks copy untracked environment files into the new worktree and set up an isolated database for it.

The payoff: after building a feature, the agent opens that isolated domain with its browser tooling and clicks through what it just built, real pages, real database, zero risk to my main checkout or shared data. Verification stops meaning "the tests are green" and starts meaning "I watched it work."

The mindset shows up in small moments too. Mid-audit, the agent noticed something odd: my dotfiles seemed to be tracked by two git systems, plain git and yadm. Instead of assuming two repos needed reconciling, it compared their git directories and index inodes, found they were literally the same repository through two front-ends, and simplified the whole operation. Evidence first, then action. When the evidence contradicts the mental model, the mental model loses.

Let it learn

A session ends; what it learned should not. Claude Code keeps memory files (small markdown notes with frontmatter that get recalled into future sessions), and my constitution defines strict rules for what goes where.

The core rule is about immediacy. The moment I correct the agent's approach, reject a tool call, or watch it retry something for the third time, it must run a reflection: what went wrong, and where does the fix belong? A one-off fact about this machine goes to memory. A general rule goes into the constitution or a rule file. A repeatable workflow becomes a skill. The reflection happens right then, not at the end of the session, because sessions stop without warning and deferred reflections never happen.

The same day the agent discovered the two-front-ends git topology, it wrote that fact into my environment rule file. No future session will burn twenty minutes rediscovering it. That is the compounding loop: every mistake becomes configuration, and the system gets harder to confuse each week.

Single mistakes are caught in-session; patterns need distance. A retro skill periodically reads my actual past session transcripts, looks for recurring friction (the same correction appearing in three different sessions, a rule that never gets applied), and proposes edits to the constitution, the rule files, or the skills. In-session reflection catches the mistake; the retro catches the habit.

And the counterweight to all this remembering: knowledge that belongs to the team goes into the versioned repo, where code review sees it, not into a private memory only my agent reads. Memory is scoped to what genuinely does not belong anywhere else.

The cockpit

A long agentic session is something you supervise, not something you watch. A handful of configuration choices turn supervision from babysitting into glancing.

The statusline, a small script Claude Code runs to render its status bar, shows me the model, a context-usage bar that shifts green to yellow to red, rate-limit percentages with their reset times, the current branch, a worktree indicator, and clickable links to the folder and the repo's web page. One glance answers the questions I used to interrupt sessions to ask.

Hooks handle attention. A Stop hook plays one sound when the agent finishes; a notification hook plays a different sound when it needs permission for something. I can be in another window, another room, or another building, and my ears tell me which of the two happened. The same hook mechanism drives the parking lot from earlier: hooks are the glue layer, small scripts that run at lifecycle moments.

Sessions run in auto mode, meaning the agent executes tool calls without asking permission for each one. That sounds reckless until you notice where the safety actually lives: in the rules, the gates, and the guards from the earlier sections. Clicking allow four hundred times a day is not a security model; it is alarm fatigue with extra steps. Auto mode is what the gates buy you.

And every session starts with remote control enabled, so the same session is reachable from my phone. The agent works through a long task, I leave the desk, a sound fires, and I steer from wherever I am.

What does not work

Now the honest part. This system has real costs.

Tokens, first. Full-content audits and parallel subagents are expensive by design; reading 193 files completely costs a multiple of what a grep would. I pulled the numbers: the audit's three sessions pushed about 136 million tokens through the model (most of them cheap cache reads), roughly 350 dollars at API list prices. My subscription absorbed it, but the meter is real. I consider it the price of the answer actually being true.

Friction, second. Human gates are wonderful for irreversible changes and mildly infuriating for trivial ones. Asking permission to commit a typo fix is the system working as designed, and it still feels like ceremony. I tune this constantly.

Maintenance, third. Skills and rules are code. They drift, they go stale, they accumulate. During the audit, Claude found five agent definition files from a third-party project sitting broken in my own config for two months: they referenced files that did not exist in my setup. I preach a self-maintaining system, and it quietly carried dead weight anyway. The system catches your cruft eventually, not instantly, and only if you point it there.

Start small

One more thing about this article: it was produced by the workflow it describes. A brainstorming skill interviewed me about angle, audience, and length before a word existed. A design spec was written, reviewed, and committed. The draft you are reading went through the same gates, and the em dash ban from my constitution applies to every sentence in it.

You do not need any of this on day one. Start with three moves. Write a CLAUDE.md with the one rule you keep repeating in every session. Add a second rule the next time you correct the agent twice about the same thing. When you notice yourself explaining a workflow for the second time, turn it into a skill.

The rest compounds from there, and all of it, the constitution, the rules, the skills, the hooks, the statusline, lives versioned in my public dotfiles: github.com/akalongman/dotfiles. One clone plus a bootstrap script reproduces the entire environment on a fresh machine (the bootstrap currently targets Ubuntu). And though the file names here are Claude Code's, the system is not: written standards, human gates, least-privilege secrets, and real verification transfer to any agent harness. Copy what looks useful. The system is the point, not the config.