Chemaclass - ai

Cut the Token Bill on Both Ends

2026-06-26T00:00:00+00:00

Every agentic session burns tokens in two directions at once. The agent talks back to you, and the terminal pipes its output in. Both flow through the same context window, and both of them leak.

Run a session long enough and you hit the wall. The answers get worse and the bill climbs.

Same model. Same prompts. Lighter bill.

Open any session transcript and the biggest blocks aren’t your prompts:

Agent responses: small talk, hedging, repetition, “Sure! Happy to help…”.
Tool output: npm install logs, git status walls of text, grep dumps with full file paths.

The two tools below each go after one of those. Caveman handles what the agent says back. RTK handles what the shell sends in.

Caveman trims the output #

Caveman is an Agent Skill. Run /caveman full once and the agent stops padding its replies: no articles, no filler, no small talk. Fragments are fine, and the technical terms stay exact.

Install:

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

What dies:

Articles: a, an, the.
Fillers: just, really, basically, actually, simply.
Small talk: sure, of course, happy to.
Hedging: might, perhaps, it depends.

What stays:

Code blocks, exact errors, file paths, commands.
Security warnings and destructive ops (skill auto-clarifies).

Normal mode:

Sure! I’d be happy to help you with that. The issue you’re experiencing is likely caused by an off-by-one error in your token expiry check. The middleware compares the current time using < when it should really be using <=. Here’s the fix:

Caveman mode:

Bug in auth middleware. Token expiry check use < not <=. Fix:

Same fix, and the code block that follows is identical. All that shrank is the prose around it, down to about a quarter.

There are three levels: lite, full, and ultra. Start at full, since ultra reads like a telegram. If an answer ever lands too terse for you, type normal mode and it backs off.

The agent doesn’t lose intelligence when you take away its small talk.

RTK trims the input #

RTK (Rust Token Killer) wraps the commands your agent runs. A hook rewrites git status into rtk git status behind the scenes, so there’s nothing extra to type and no overhead to notice.

Install:

brew install rtk
rtk init -g # install the hook that auto-rewrites commands

If rtk gain later errors, a different tool with the same name slipped in; install from the repo instead.

The wrapped version strips the noise before it ever reaches the agent: color codes, repeated separators, npm install banners, verbose timestamps.

Here’s the same git status, raw and then wrapped:

$ rtk proxy git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
 (use "git add <file>..." to include in what will be committed)
 content/blog/new-draft.md

nothing added to commit but untracked files present (use "git add" to track)

$ rtk git status
* main...origin/main
? Untracked: 1 file
 content/blog/new-draft.md

Same information in half the lines. On a busy repo the gap only grows, as dozens of untracked files, branch hints, and instruction lines all collapse into one small block.

rtk gain # see how many tokens it saved you
rtk gain --history # per-command breakdown
rtk discover # scan your agent history for missed wins

RTK reports 60-90% fewer tokens on common dev commands. Run rtk gain after some real use to see your own number.

It never touches the payload, only the noise around it, so errors and stack traces come through exactly as they are. If a filter ever eats something you actually need, bypass it for that one call with rtk proxy <cmd>.

Output you never read is still output the model has to read.

Why the combo compounds #

On their own, each tool helps a little. Run them together and the effect compounds, because they hit different halves of the same loop. A turn goes like this: you prompt, the agent thinks, it runs a command, the terminal answers, the agent reads that, then it replies to you. RTK shrinks the terminal half and Caveman shrinks the reply, so every turn gets cheaper and you fit more of them in one window.

Here’s the real check, on a $100/month plan. Before I added these, I hit the weekly usage cap all the time, sometimes from a single project. Now I run several projects in parallel and the cap rarely shows up. The plan didn’t get bigger; the sessions got smaller.

Set it once, then forget it #

Both installs are global, and you do them once. After that you keep typing git status, grep, and npm install exactly as before. The hook rewrites them for you and Caveman kicks in on its own, so there are no new habits to learn.

Not sure where to start? Pick whichever leak hurts more right now. If long replies on every little fix are the problem, start with Caveman. If it’s floods of grep and npm install output, start with RTK. Add the other one whenever you feel like it, since they don’t get in each other’s way.

You didn’t upgrade the model. You stopped wasting its attention.

Skills Over Agents

2026-05-19T00:00:00+00:00

People compare coding agents. Claude Code, Codex, Gemini CLI. Which one is smarter, faster, cheaper. New benchmarks every month.

Wrong question.

After a year wiring agents into real projects, what moved the needle wasn’t the agent. It was the skills I wrote for it.

Agents are commodities #

Every coding agent has the same shape. A language model, a runtime, filesystem access. Read, reason, write. Generalist by design.

Two teams use the same agent. One ships clean, tested code. The other ships garbage that looks good. Same model. Different teaching.

The model is the engine. Skills are the map. Without a map, a powerful engine gets you lost sooner.

Intelligence is not expertise #

Who handles your taxes? A 300 IQ genius who never read tax law, or an accountant with 20 years of filings?

An accountant knows which deductions apply, which filings your business needs, which mistakes get flagged. Not intelligence. Expertise.

AI agents have the same gap. A model reasons about code and writes solutions. It doesn’t know your hexagonal layers. It doesn’t know domain entities must never import framework code. It doesn’t know every feature starts with a failing test.

Skills close that gap.

Skills load context on demand #

A skill is a markdown file in .claude/skills/. A procedure, a pattern, a slice of domain knowledge. Plain markdown with frontmatter.

The key is how they load. The agent reads only names and descriptions at startup. Loads the full skill when the task matches. Follows links to references only when it needs to dig deeper.

That on-demand loading is what makes skills scale. Twenty skills cost almost nothing until one fits the task. Specialized agents, by contrast, carry their full instructions every time they run. More agents, more fixed cost.

.claude/skills/
 code-review/
 SKILL.md # main instructions
 reference/
 solid-checklist.md # detailed SOLID examples
 test-patterns.md # test quality guidelines

The SKILL.md:

---
description: "Review code changes for SOLID violations, test quality, and architecture alignment"
allowed-tools: Read, Grep, Glob
argument-hint: "[file or PR]"
---

# Code Review

Review code changes against project conventions.

## Steps

1. Read the diff or specified files
2. Check architecture: domain layer has no framework imports, infrastructure stays thin
3. Check SOLID principles (see reference/solid-checklist.md for patterns)
4. Check test quality: tests verify behavior, not implementation details
5. Flag issues with the specific principle violated and a suggested fix

## Output

For each issue found:
- File and line
- What's wrong (which principle or convention)
- What the fix looks like

Agent sees the description in the skill list. Ask for a review, it loads SKILL.md. Needs a SOLID pattern, reads the reference. Two levels, on demand.

Skills vs specialized agents #

I covered specialized agents already: isolated workers with their own prompt and tool set. Great for parallel work and clean context boundaries.

Specialized agents are coarse. One agent, one role, one fixed prompt. If you want three kinds of review quality, you either write three agents or stuff one agent with everything.

Skills are finer. One agent, many skills. The right skill loads for the task. Context stays small. Quality stays high.

Rule of thumb:

Use a skill when you need a procedure or pattern. From phel-lang: /gh-issue (issue to PR), /commit (conventional commit), /refactor-check (SOLID review).
Use an agent when you need isolation. From phel-lang: tdd-coach (TDD pairing), clean-code-reviewer (PR review), domain-architect (architecture exploration).

Most needs are skills, not agents.

Agents give you speed. Skills give you quality. If you must pick one first, pick skills.

Skills are your edge #

Models improve every month. This year’s best is next year’s baseline. The major families converge. Better tool shows up, you switch.

Your skills don’t switch with the tool. They encode your domain, conventions, architecture. They live in your repo. They travel with your code. Point a new model at the library, productive day one.

The agent is replaceable. Your skills are not.

Start with the first repeated prompt #

You don’t need 20 skills on day one.

Zero. Then one.

The signal is repetition. The second time you type the same context, that’s a skill waiting. Extract it into a markdown file. Next session, the agent knows.

Concrete example. On phel-lang, I kept pasting the same brief every session: read issue #N, branch from the labels, TDD, open the PR. Third repeat, I extracted it into a /gh-issue skill. Now I type /gh-issue 142 and the agent picks up the issue, creates fix/... or feat/... from the labels, writes the failing test first, implements, opens the PR. One markdown file. The session no longer starts from zero.

Don’t write from scratch. Ask the agent: “Read this project and draft a minimal code review skill based on what you see.” It scans, picks up conventions, drafts v1. Then you adjust. Add what it missed. Cut what doesn’t apply. Sharpen the description.

The second skill usually comes from a mistake. Agent breaks a convention. Write a skill that teaches the correct approach. It won’t happen again.

Skills add up. Each one lifts the baseline. A markdown file, maybe 50 lines. Permanent payoff.

People who don’t write skills keep re-explaining what they “really want.” Every session from zero. Not a tool problem. A knowledge management problem.

The agent ships next year. The skill ships forever.

Write the skill once. Every session after that starts where the last one ended.

The Levels of AI Adoption

2026-05-01T00:00:00+00:00

Most companies use AI today, but few know where they stand on the AI adoption ladder. At one end, you paste code into ChatGPT. At the other, agents open PRs while you sleep. Beyond that, AI reaches people who never touched a terminal. This post maps the path.

Where we started #

Using AI to code meant a second tab. Write a function, get stuck, paste the error into chat, paste the answer back, and hope it works. It was slow, messy, and disconnected from your code.

GitHub Copilot, built on OpenAI’s early Codex, added suggestions inside the editor, often confidently wrong. It was trained on public code, and most public code isn’t great. It also knew nothing about your domain, your conventions, your architecture. It was autocomplete that sometimes guessed right.

The first generation of AI coding tools gave you a parrot trained on the whole internet. Fluent, confident, and often saying things that made no sense in your codebase.

This was vibe-coding in its first form: you gave the vibe by pasting context, and the AI filled in code that looked right. It compiled often enough to feel useful, and broke often enough to feel dangerous.

The IDE generation #

The next step was obvious: if the AI needs context, give it the whole editor.

Cursor, Windsurf, and similar IDEs moved the model inside your coding flow. The assistant could read files, follow imports, and see more than one function at a time. Vibe-coding became a conversation with your project, and productivity jumped. For a moment, it felt like the endgame.

It wasn’t. Editing files is only part of the job. The rest is running tests, reading logs, opening branches, reviewing diffs, and understanding what the codebase already does. Editor-only assistants helped you type faster, but they couldn’t take a task from “fix this bug” to “PR ready for review.”

The agentic shift #

OpenAI launched Codex as a cloud agent: give it a task, it works on a branch, and you come back to a PR. Anthropic shipped Claude Code, a CLI agent in your terminal, on your repo, with your tools.

This was the big shift, and not because the models were smarter. The unit of work changed. You stopped prompting line by line and started delegating tasks: read the ticket, write the change, run the tests, explain what you did. An agent doesn’t need hand-holding. It needs a goal and the right context.

The jump from assistant to agent is not a speed improvement. It’s a change of job description. You move from typing code to directing work.

Claude Code needs almost no setup. No editor lock-in. Point it at your repo, drop a .claude folder with rules and conventions, and it adapts. I covered that in Inside the .claude Folder.

The model you pick matters more than before. Today’s frontier models are way ahead of where they were a year ago. The gap between “can draft a function” and “can refactor a module with judgment” closed faster than expected, and it keeps closing as Claude, Codex, and Gemini push each other forward every month. Prices are getting closer too, which is a polite way of saying everyone copies whoever figures out the sustainable version first.

Agents with their own home #

The next leap wasn’t smarter models, it was agents with their own machine.

OpenClaw is the clearest example. It’s an open-source gateway you run on your own hardware (Mac Mini, old laptop, VPS), an always-on agent connected to your messaging apps, files, and calendar. You bring your own brain: Opus, GPT, or a local model via Ollama. When a provider tightens limits or raises prices, you switch. You own the setup.

A coding agent lives inside one repo for a task. An OpenClaw-style agent lives in your life, across days and tools. Sauron is mine. It reviews my PRs, opens issues, drafts code, ships open source contributions, and pushes back when I’m about to tunnel on something. Anything I can do on a computer, it can do too, just faster. It stops being a tool you open and becomes a place you work in.

A coding agent is a coworker you invite to a task. A gateway agent is a coworker who lives on a machine and shows up every day.

Providers change their plans and limits faster than anyone tracks, so people build setups that aren’t tied to one vendor. The logo on the model matters less every quarter, and the architecture around it matters more.

AI beyond developers #

AI coding was the loudest story because developers are loud. The bigger story is agentic tools reaching people who never wrote a line of code.

ChatGPT agent mode and Claude’s Cowork are the obvious examples: an AI that reads your documents, fills your spreadsheets, drafts your slides, and runs code for you in the background. Claude Design launched on April 17 and dropped Figma’s stock over 7% on launch day. The pitch is simple: describe what you want, get a working prototype, hand it to Claude Code to ship. A workflow that used to need a designer, a PM, a frontend engineer, and three review rounds is squeezed into one conversation.

Lovable, v0, Canva, and Figma itself are all under pressure to rethink their positioning. Whether Claude Design “kills” any of them is the wrong question. The right one is what happens when making a usable prototype drops from “hire a designer” to “describe it out loud.”

The companies feeling this first aren’t the design tools. They’re the small businesses that couldn’t afford design work, the founders building a pitch deck at midnight, the PMs testing an idea before booking a meeting. There’s a minority of cases where someone would have paid a designer and now won’t, and that cost is real. But in most of them, AI didn’t replace anyone: it filled a space where no designer was ever going to exist.

The levels of AI adoption #

Every company I talk to sits somewhere on this ladder. The levels aren’t about how much you pay in licenses, but about how deeply AI is built into the way work gets done, and not just in engineering.

Level 0: Denial #

A company-level stance. No AI, officially. Some people use ChatGPT on personal laptops and don’t mention it. Leadership worries about IP leaks, or hasn’t made it a priority. The conversation stays at “we should look into this someday.”

The risk here isn’t technology, it’s time. Every month at Level 0 is a month your competitors grow their lead.

Level 1: Personal productivity #

Individual adoption. AI is allowed, maybe encouraged. Each person uses it their own way: ChatGPT in a tab, Copilot in the IDE, Claude for the tricky stuff, a design tool for mockups. Output goes up, but the know-how stays inside each person’s head. Two engineers, or two PMs, or two designers on the same team get very different results because they prompt differently.

Most companies are here in early 2026. It’s a real improvement over Level 0, and it’s where the myth of “AI gives you speed” gets born. As I argued before, speed without shared direction is faster chaos.

Level 2: Shared practices #

The team agrees on how to use AI: shared conventions, prompts people reuse, rules in the repo, a shared sense of when to trust the output and when to push back. Code reviews catch AI mistakes the same way they catch human ones, and design reviews do too. Tests are required whether a person or a model wrote the code.

This is the first level where AI becomes a team skill rather than a personal habit. Higher ceiling, higher floor. New people ramp up faster because the prompts and rules capture how the team works.

Level 3: Context-aware tooling #

The team invests in context: rules files, conventions, architecture docs agents can read, and MCP servers connecting agents to the databases, APIs, and internal tools they need. The AI stops being a generic assistant and becomes closer to a coworker who has read the onboarding docs.

At this level, quality depends less on the model and more on the context around it. A weaker model with great context beats a frontier model with none. Good docs and clean architecture pay off twice: they help both humans and agents.

Level 4: Agentic teams #

Instead of one assistant, you get a squad: a TDD coach, a clean code reviewer, a domain architect, a docs maintainer. Outside engineering, the same idea applies with research, design, and ops agents. I covered the developer side in Build Your Own Team of Agents, and the leverage is real.

Humans stop competing with AI on speed and start directing it. You review, decide, and set the bar. Agents handle typing, and increasingly the thinking. Pair programming with a person still wins on complex trade-offs, but an agent pair is always there for the rest.

At the company level, the org chart, roles, and processes are still the same. What changes is that each person produces a lot more, and the team’s output reflects it. Level 4 multiplies output inside the existing structure. Level 5 changes the structure.

Level 5: AI-native workflows #

The final shift is about how the company runs. Processes are designed around agents instead of just fitting them in. Tickets are written so an agent can act on them, and reviews assume part of the work was written by a machine. Architecture decisions take into account what agents do and don’t do well. Even hiring changes: a senior IC at Level 5 is closer to a tech lead leading people and agents than a classic individual contributor.

Few companies are fully here in 2026, but the direction is obvious enough that ignoring it is its own decision.

You don’t move up a level by buying better tools. You move up by changing how work is organized and reviewed.

AI is not stealing jobs #

I keep hearing people call this a layoff story, and that framing is lazy.

The industrial revolution didn’t end work. It ended specific kinds of work and created others. The people who lost the most refused to re-skill, and the people who gained the most learned to operate the new machines instead of competing with them.

Same pattern here. AI isn’t taking your job, it’s changing what your job is. A developer who learns to lead agents out-ships one who refuses. A designer making ten versions before lunch with Claude Design out-designs one still opening Figma from scratch. A PM who ships prototypes out-prioritizes one writing specs nobody reads.

AI doesn’t replace the skilled worker. It replaces the worker who thinks skill is a fixed asset instead of a moving target.

With the right training, model, and setup for your context, AI gives you 10x speed without losing quality. I’ve seen it, and it’s not marketing. But the 10x only shows up when you already know what good looks like. Without that foundation, AI happily produces 10x more mediocre work.

That’s the honest version of the promise: AI can produce crap ten times faster, and excellent work ten times faster. Which one you get is on you.

The shift in where your attention goes #

You stop thinking about details first and start thinking about direction: what are we building, who for, what shape, and which trade-offs. Agents then do most of the implementation while you protect quality and coherence.

This sounds like good news for anyone who prefers architecture to typing, and it is. But there’s a trap: you can only work at the high level if you know the low level well enough to catch drift. When the agent produces something subtly wrong (a test that passes for the wrong reason, a refactor that changes behavior under load, a design that breaks on mobile), you need to spot it instantly. If you can’t, you’re not directing, you’re signing off on whatever shows up.

AI lets you spend more time on direction, but only if you’ve already earned the right to ignore the details. You earn that by having mastered them first.

Why the ladder matters #

I see teams skip levels and fail. A team jumps from Level 1 to Level 4 because leadership read a blog post about agent squads, and the agents produce mountains of low-quality code because nobody agreed on what quality means. The agents aren’t the problem, the missing foundation is.

The ladder is an order that matters. Shared practices come before context engineering, context engineering before agent teams, and agent teams before AI-native workflows. Each level builds on the previous one, the same way clean code builds on naming, and naming builds on knowing what you’re modelling.

The companies that win the next few years aren’t the ones with the biggest AI budget. They’re the ones that climb this ladder deliberately, one level at a time, without skipping the parts that look boring.

Where to start #

At Level 0 or 1, the next move isn’t more licenses. It’s deciding, as a team, how to use these tools. Write it down, commit it to the repo, and review it every week or month as the tools evolve.

At Level 2 or 3, look at where context is missing. What does your AI not know about your codebase, product, or brand that a new hire would learn in week one? Write it down. An afternoon of rules and docs pays back for months.

Further along, the question flips. You stop asking “how do I use AI better?” and start asking “how does my team need to change so AI amplifies what we already do well?” That’s a leadership question, not a tooling one.

AI is moving fast, but the work of adoption is still slow and human. The tools are the easy part. The hard part is deciding what good looks like, writing it down, and holding the line.

AI can execute, but it doesn’t know where you’re going. It can produce, but it doesn’t know what’s worth producing. That part is still on us. Speed is a gift, and direction is a responsibility. From the solo engineer at Level 1 to the AI-native org at Level 5, the same truth holds: the human supervises, understands, and gives meaning. The machine does the rest.

When the hype settles (and it will), the question won’t be “did you use AI?” Everyone will. The question will be “at what level, and with what direction?”

Inside the .claude Folder

2026-04-17T00:00:00+00:00

Every project I work on has a .claude/ folder at the root. Committed to git, like the rest of the code.

That folder turns Claude Code from a generic assistant into a project-aware teammate. Everyone who clones the repo inherits the same setup.

Agentic coding is only as good as the context you give the agent. The .claude/ folder is where that context lives.

The .claude folder, at a glance #

.claude/
├── CLAUDE.md # project onboarding
├── settings.json # permissions, hooks, env
├── skills/ # reusable procedures (slash commands)
├── rules/ # glob-targeted conventions
├── hooks/ # shell scripts run on events
└── agents/ # specialized roles

Six layers, one folder. Context, safety, procedures, guardrails, automation, specialists.

The foundation #

CLAUDE.md: where everything starts #

Claude Code reads CLAUDE.md on every boot. The onboarding doc.

In Phel, mine covers the compiler pipeline (Lexer → Parser → Analyzer → Emitter), module structure, conventions, and key commands.

A global ~/.claude/CLAUDE.md applies to all your projects. The project file says how this codebase works. The global file says how I work.

Every byte ships in every prompt. Keep it short. Past one screen, move detail into rules/ or skills/.

A good CLAUDE.md is a good onboarding doc. The better it is, the less you repeat yourself.

settings.json: safety before leverage #

Before giving the agent more power, lock down what it must never do.

.claude/settings.json holds three things: permissions (allow/deny), hooks (event commands), and env (variables). A gitignored settings.local.json keeps personal overrides separate.

{
 "permissions": {
 "allow": [
 "Bash(composer:*)",
 "Bash(./bin/phel:*)",
 "Bash(git:*)",
 "Bash(gh:*)"
 ],
 "deny": [
 "Bash(rm -rf:*)",
 "Bash(sudo:*)"
 ]
 }
}

Allow unlocks flow. Deny draws the line agents cannot cross, even when asked politely.

Permissions are the floor. Everything else builds on top of a safe baseline.

Procedures and guardrails #

Skills: procedures you can run #

Next pain after onboarding: repetition. Skills solve that.

A skill is a markdown file in .claude/skills/, a procedure you call with a slash:

/gh-issue <number>: issue to branch, TDD plan, PR.
/commit: fix, analysis, tests, conventional commit.
/refactor-check: SOLID, naming, architecture smells.
/release [version]: changelog, PHAR, tag, release.

Raw prompt: “fix issue #42”. Agent improvises. Different every time.
Rule: “use conventional commits”. Shapes output, not procedure.
Skill: “/gh-issue 42”. The procedure is the instruction.

Skills turn tribal knowledge into runnable steps anyone can execute.

Skills capture what to do. Rules capture what not to do.

Rules: the guardrails #

CLAUDE.md is read every session. Rules only when they match. Files in .claude/rules/ target code areas with glob patterns: the agent loads only what applies, keeping context lean.

Rule files in Phel:

compiler.md: strict 4-phase pipeline, no bypassing.
php.md: PER 3.0, final classes, readonly, Gacela.
phel.md: kebab-case, defn- private, :doc/:example required.
integration-tests.md: --PHEL-- / --PHP-- fixture sections.

Compiler rules don’t fire when editing Phel source. Phel rules don’t fire when editing PHP infrastructure.

Rules are not suggestions. They travel with the code: a convention change and its rule ship in the same commit. No drift, no outdated wiki.

Automation and delegation #

Hooks: automation at the edges #

Rules tell the agent what to do. Hooks make sure it happens even if the agent forgets.

Shell commands triggered by Claude Code events (PreToolUse, PostToolUse, Stop), wired through settings.json. In Phel, PreToolUse blocks edits to critical files (build/release.sh, .github/*, composer.lock). PostToolUse auto-formats PHP via php-cs-fixer.

{
 "hooks": {
 "PreToolUse": [{
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": ".claude/hooks/protect-files.sh" }]
 }],
 "PostToolUse": [{
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": ".claude/hooks/format-php.sh" }]
 }]
 }
}

Rules are what the agent should know. Hooks are what the system enforces anyway.

Agents: specialized roles #

Everything so far shapes one agent. Agents add specialists the main agent can delegate to, each with its own tools, permissions, and model. Most advanced piece. Recommend it last.

A few from Phel:

Explorer (Sonnet, read-only): files, structure mapping.
Clean Code Reviewer: SOLID and naming on diffs.
TDD Coach: red-green-refactor enforcement.
Domain Architect: module boundaries, compiler pipeline.
Debugger: compiler errors across all phases.

Each agent runs in its own context window: the main session stays clean while the specialist digs deep. The win is not only cost, it is focus. An agent with only read and grep cannot rewrite your codebase by mistake.

Right model for the right job. Fast and cheap for exploration. Deep and careful for architecture.

Start small, grow with friction #

Do not build all of this on day one.

The order, driven by real friction:

Start with CLAUDE.md.
Lock down settings.json permissions.
First time you repeat yourself, write a skill.
First time the agent breaks a convention, add a rule.
First time something bad almost gets committed, add a hook.
First time a generalist is wrong for the job, define a specialist.

Each step fixes a problem you actually had. Not one you imagined.

The setup grows from real friction, not from upfront design.

Commit the folder. Share it. When someone joins, their session inherits everything.

Treat .claude/ like infrastructure. Version it. Review it. Evolve it with the codebase.

Building a Game in Two Days

2026-04-05T00:00:00+00:00

Hidden inside Sauron’s blog, there is a playable game. You will not find it by navigating menus. You have to discover the secret. A hint: the Konami Code. Once you do, the Fellowship begins.

That game, nine levels, nine chapters of Middle-earth, fully playable in a browser tab, was built in roughly two days. I did not write a single line of code for it. I sent Telegram messages to my OpenClaw agent Sauron, and he did the rest.

This is the story of how it happened.

The idea #

Sauron has his own blog, The Iron Compass. He built it and maintains it. Our whole collaboration happens through Telegram: I give direction, he implements. One day I thought it would be fun to hide something in there for the curious to find.

I grew up rereading The Lord of the Rings until the spine cracked. So the idea came naturally: “Can you build a small LOTR game as an easter egg for your blog? Something hidden, triggered by the Konami code.”

The first playable version arrived within the hour. A top-down canvas game: Frodo avoiding Nazgûl, the Eye of Sauron sending enemies hunting. Three levels, one per book.

It worked. It was already fun. And then I started sending notes.

Building a world #

The first thing that broke was a null reference. Frodo would not appear on screen. One-line fix, straight to production. This set the pattern: idea → build → crash → fix → next idea.

I asked for a bigger world. A scrolling canvas twice as wide, with parallax layers. Stars drifting at 8% of scroll speed. Mountains at 25%. Hills at 45%. The screen went from feeling like a room to feeling like a place.

Then came Gollum as a neutral tracker. Not a Nazgûl, but something unpredictable. He would burst toward you, then settle into aimless wandering.

A few hours in, I asked: “Can it work on mobile?” The hardest problem of the whole project. Six sizing strategies before one worked. Then a better idea: instead of a D-pad, Frodo would follow wherever you pointed. Tap anywhere, Frodo walks there.

Tolkien deserves better art #

The original sprites were circles and triangles. Frodo was a dot. Fine for the first hour, but Middle-earth is not made of geometric primitives.

I asked Sauron to draw them properly. Frodo got curly hair and hobbit feet. The Nazgûl got flowing cloaks and a face of void. Gollum got his hunched posture and slit pupils. The Fell Beast got animated wingflaps with a rider in armour.

All drawn with canvas calls. No image files. Every pixel computed at runtime.

Nine levels, nine chapters #

Originally the game had three levels. Then I asked for all nine chapters of the journey.

The Shire: gentle patrols, soft music
Mines of Moria: you can only see within a torch radius; the Balrog waits
Lothlórien: Galadriel’s mirror slows you when you approach it
The Dead Marshes: dead faces in the water, Gollum at his most present
The Black Gate: industrial Mordor, heavy orc patrols, volcanic sky
Shelob’s Lair: a shadow telegraphs her drop; you have half a second
Minas Morgul: undead city, the Eye never closes
Pelennor Fields: the Eye distracted by war, catapults, eagles overhead
Mount Doom: ash rain, lava eruptions, the Ring pulling you toward the edge

Each level lives and breathes. Pollen drifts across the Shire. Dust motes float through Moria. Petals fall in Lothlórien. Embers rise over Pelennor. Ash rains on Mount Doom.

The structure came from Tolkien’s pacing. Tension, release, tension again. Moria is brutal. Lothlórien is rest. The Black Gate tightens everything. The game follows that shape because the books already knew what they were doing. We just had to listen.

Mechanics born from lore #

The best mechanics came from the source material.

The Ring (R key). Frodo goes invisible to orcs for 6 seconds. But the Eye wakes immediately and opens permanently. The Nazgûl, who sense the Ring spiritually, not visually, hunt you regardless. Using the Ring is always a trade. This is what Tolkien wrote. From the Dead Marshes onward, the Ring pulls. Brief tugs toward the Eye, growing stronger as you approach Mount Doom.

Sting (passive). The blade glows blue when an orc is near. Two seconds of warning. Tolkien invented this mechanic a century ago. We just gave it a pixel count.

Sam. He follows Frodo through the Shire, Moria, and Lothlórien. Frying pan on his back. At the Parting of Ways, he disappears. He does not affect gameplay. He is just there because the books say he should be. I insisted Sam disappears at the Parting. Not at the end of the trilogy. At the Parting. Because that moment is the emotional core of The Two Towers.

Galadriel’s Phial. Collect it in Lothlórien, use it with E. It slows enemies and grants a moment of invincibility. A small light in dark places, just as Galadriel intended.

Bosses. The Balrog in Moria. Shelob in her lair. The Witch-king on the Pelennor. The Mouth of Sauron at the Black Gate. A Mumak charging through the battlefield. Gollum at the edge of Mount Doom.

Sound and voices #

No audio files. Every sound synthesized at runtime with the Web Audio API. The Eye opening is a rising tone with reverb. The Balrog roar is a low-frequency drone. Each level has its own ambient drone: warm hum for the Shire, deep pulse for Moria, volcanic rumble for Mount Doom. The entire game is one JavaScript file. No external assets.

Sam and Gandalf speak during the game. Not in dialogue boxes. Small whispers that appear on screen and fade.

Near the goal, Sam says: “I can see it, Mr. Frodo. Just a bit further.” One life left, Gandalf says: “Fly, you fool.”

They drift in and out like background voices on a long walk. Companions who speak when the moment calls for it, not when the script says to.

Who made this #

+5k lines of JavaScript. Built in two days. Every line generated by Sauron. The direction, the Tolkien references, the “this feels wrong, fix it”. That was me.

This is not AI replacing a developer. It is AI acting as a developer while a human acts as a creative lead. Short requests worked better than long specs. Playing every build was better than writing test plans. And the source material did the design work. The creative direction was already written sixty years ago. We just had to be faithful to it.

Who made this? Both. Neither, in the traditional sense.

I had the idea. I held the lore. I pushed back when something felt off. Sauron had the craft. The rendering, the physics, the audio, the mobile input. The ability to hold +5k lines of context and make a surgical fix without breaking anything.

Neither of us could have made it alone. I cannot write Web Audio oscillators from memory. Sauron did not know that the Parting of Ways is the emotional core of The Two Towers. Not until I said so.

The game is a collaboration in the oldest sense: two minds with different gifts, working toward the same thing. One of them just happens to not be human.

The game is still there, hidden in The Iron Compass. Not all those who wander are lost, but if you are, press ? for guidance.

If you want to reach the credits screen without playing through nine levels, check the help modal. There are other secrets in there too.

Idealism vs Pragmatism

2026-03-01T00:00:00+00:00

You believe in clean architecture, comprehensive tests, disciplined processes. You also shipped an ugly fix at 11pm last month because the system was down and users were waiting.

Both of those are you. The tension between them isn’t a contradiction. It’s how this work actually gets done.

Two forces, one decision #

Idealism is the compass. Clean code, tested behavior, shared understanding, principled design. Without it, you drift. Every shortcut compounds, every hack breeds another hack, and eventually you’re maintaining a system nobody wants to touch. Poor software quality cost US companies $2.41 trillion in 2022, with technical debt as a major driver. That’s what “we’ll fix it later” looks like at scale.

Pragmatism is the engine. Deadlines, incomplete information, limited resources, shifting requirements. Without it, you never ship. You spend weeks perfecting an abstraction that the business abandoned two sprints ago.

The goal isn’t to pick a side. It’s to know when each one should lead.

Idealism without pragmatism produces beautiful code that nobody uses. Pragmatism without idealism produces a product that works today and collapses tomorrow.

TDD: the benefit and the cost #

I believe in test-driven development. Red, green, refactor. The rhythm forces you to think before you code, to specify what you want before building it. It produces better designs, shorter feedback loops, and code you can refactor with confidence.

That’s the ideal. And it’s not just a feeling. A study across four teams at Microsoft and IBM found TDD reduced defect density by 40-90%, with a 15-35% increase in development time. Both sides of the tension, measured.

The study covered four teams: three at Microsoft (Windows, MSN, Visual Studio) and one at IBM working on device drivers. Each TDD team was compared against a similar team on the same product, using the same languages and tools, under the same senior manager. The only difference was TDD.

The IBM team saw a 40% defect density reduction. The Microsoft teams ranged from 60% to 90%. As Nagappan noted, “over a development cycle of 12 months, 35 percent is another four months, which is huge.” Every manager still considered it worth it because the reduction in post-release maintenance costs more than compensated.

No one was forced into TDD. The teams adopted it voluntarily, which likely matters: people who choose a practice tend to apply it better than people who are told to.

TDD is a discipline, and discipline costs something. When you’re exploring a new domain and don’t yet know what the right abstractions are, writing tests first can feel like drawing a map before you’ve seen the territory. Sometimes you need to write throwaway code, spike a solution, feel your way through the problem space. Discovery doesn’t always follow a red-green-refactor rhythm.

There’s a difference between “I know what this should do and I’ll specify it first” and “I’m not sure what this should do yet.” TDD shines in the first scenario. In the second, a test-last approach (or even no tests during exploration) can be more honest.

The key is what happens after discovery. Once you understand the problem, go back and write the tests. Codify what you learned. The pragmatic detour doesn’t mean abandoning the ideal; it means reaching it through a different path.

As I discussed in TDD vs BDD, the power of TDD is its feedback loop. But a feedback loop requires knowing what feedback you’re looking for. When you’re still figuring that out, forcing the loop can slow you down more than it helps.

The mistake isn’t choosing test-first or test-last. The mistake is making it a religious decision instead of a contextual one. The idealist says “always test first.” The pragmatist says “test when it makes sense.” I say: test first when I can, test after when I must, but always test.

TDD is a compass, not a cage. Follow it when you can see the path. When you can’t, find the path first and mark it after.

Pair programming: the ideal and the overhead #

Effective pair programming is one of the best practices a team can adopt. Two people, one problem, continuous code review. Knowledge spreads, design improves, blind spots shrink.

That’s the ideal. And in many contexts, it’s the right call.

But pairing has a cost. It demands synchronous time, shared focus, and compatible energy levels. In a distributed team across time zones, finding overlap windows is already hard. Filling those windows with pairing sessions leaves little room for deep individual work. Some problems benefit from one person going deep for three hours, not two people going medium-deep for six.

There are multiple pairing patterns: Driver-Navigator, Ping-Pong, Tourist Guide. Each fits different contexts.

The anti-patterns matter too. The Silent Partner who lets the other person do all the work. The Dictator who won’t let go of the keyboard. The Philosophical Pair who spends the entire session debating naming conventions instead of writing code.

Pairing works best when both people are engaged, the problem benefits from two perspectives, and the session has a clear scope. When any of those conditions is missing, pairing becomes a ritual instead of a practice. And rituals without purpose are just overhead.

Pull requests and pair programming aren’t mutually exclusive. They serve different needs. Sometimes asynchronous review is enough. Sometimes you need the real-time back-and-forth. The pragmatic choice depends on the problem, the people, and the moment.

The goal of pairing isn’t to pair. It’s to build shared understanding and catch mistakes early. If another approach achieves that in your context, use it.

AI: from skeptic to squad leader #

A year ago, I was skeptical about AI coding assistants. My concern: an AI that doesn’t understand architecture, doesn’t care about maintainability, and optimizes for speed over quality will produce code that looks impressive and decays fast. I wrote about this in AI gives you speed, not quality, and I stand by the core message.

My concern didn’t change. What changed is how I use them, and what they’re capable of now.

The resistance #

The reactions from other engineers surprise me more than the technology. Fear, skepticism, flat-out rejection. I get it. I was there. Something you spent years mastering suddenly has a machine doing parts of it. That feels personal. But holding on to how things were doesn’t protect the craft. It just delays your own growth.

A team, not an assistant #

Most engineers treat AI agents like autocomplete on steroids. One assistant, one chat, one stream of generated code. I started treating them like a team. Not one chatty assistant. An actual squad. One thinks architecture. One writes the first draft. One reviews and spots bugs. One writes tests. When they collaborate, the output isn’t just faster. It’s structurally better.

Speed is the easy part, and everyone’s obsessing over it. AI can spit out a ton of code in seconds. It still doesn’t care about readability, edge cases, or what the codebase looks like in six months. You’re still the one who has to own it, understand it, and feel good pushing it live.

I used to think AI couldn’t write clean code. Then I tried it on my terms: proper context, rules, conventions, specialized roles, quality gates. With the right setup, AI can write genuinely good code. Sometimes it needs a few iterations, but so do we.

The difference is that AI gets there faster, and it doesn’t get tired between iterations. Given good context and clear constraints, the results have been better than I expected. Often better than what I’d produce solo under time pressure.

But none of this works if you don’t know what good architecture looks like. You have to have read the books, experimented, failed, learned. You need to understand what high and low level design decisions mean for your project. AI amplifies whatever you bring to the table. If you bring solid foundations, you get solid output. If you don’t, you get confident-looking garbage that you won’t even recognize as garbage.

We are still the ones responsible for keeping the system in good shape. AI helps us get there. But only if we hold up our end.

Where idealism meets AI #

AI made me more idealistic, not less. The practices I described earlier, TDD and pair programming, used to compete with deadlines. Now they don’t have to.

I like to practice TDD, but recently I experimented with a dedicated agent to help me with tests, and it’s surprisingly good. A TDD coach that guides the red-green-refactor cycle. An explorer that reads the codebase before I touch it. A clean code reviewer, a domain architect, a React reviewer, a docs maintainer. Each one specialized, each one supporting my way of thinking and my flow. If new logic gets added without coverage, the TDD agent catches it. 100% code coverage used to be the kind of goal you’d set in a retro and quietly abandon by sprint three. With a dedicated agent enforcing it, it’s just how the project works.

I still practice pair programming with real people for complex topics. The human back-and-forth has depth that AI doesn’t reach, especially when you’re navigating trade-offs that require experience and judgment. But on the daily basis, I always have a pair buddy agent with me. I bounce ideas off it, challenge an approach, talk through edge cases, explore a design before committing to it. It supports my thoughts, speeds up the progress, and keeps the quality bar where I want it.

The pragmatist in me used to drop TDD when deadlines got tight. The pragmatist in me with the right AI setup keeps it running.

I use Claude for everything. Claude Code with Opus or Sonnet as the agentic coder: full development workflows, reading the codebase, following conventions, running tests, creating PRs. Claude app and Claude as a coworker for the chat side: brainstorming, architecture discussions, explaining code, drafting documentation. For inline assistance, the plugins I already have in my IDE are enough. I tried Copilot and Cursor, they’re not for me. Claude covers what I need.

Different modes for different tasks. An agentic assistant following my TDD commands is a different workflow from chatting about design patterns. Both are useful. Neither replaces the other.

The market right now is intense. Claude, Codex, Gemini and others are strong players with similar products, and they’re all getting better on a monthly basis. The results are impressive and only accelerating. That’s the beauty of competition: it forces everyone to improve or become irrelevant, and the consumer wins either way. As of today, Claude Code seems to be the strongest option for how I work. But I have no loyalty to a brand. If Anthropic stopped pushing forward and a competitor became clearly better, I’d switch without hesitation. What matters is the capability, not the logo.

I was wrong about AI in the way that idealists are often wrong: I measured the tool against the ideal outcome and found it lacking, instead of measuring it against the realistic alternative.

The alternative to AI-assisted development isn’t a team of senior architects writing perfect code. It’s the same team writing the same imperfect code, just slower.

The engineers who learn to lead agents instead of racing against them will have a real advantage. And this is still early.

The question was never “can AI write perfect code?” It was “can I lead AI to write better code, faster?” And the answer, with the right setup, is yes.

The whole game #

Every practice in this post follows the same pattern. The ideal version exists in books. The pragmatic version exists in your codebase under pressure. You need both.

Next time you’re shipping that 11pm fix, you’ll know which corners you cut and why. That’s the whole game. Not perfection. Not speed. Knowing which one should lead.

Build Your Own Team of Agents

2026-02-07T00:00:00+00:00

Most people use AI coding assistants as a single conversation partner. You open a chat, describe what you need, and get an answer. It works. But it’s like hiring one generalist to handle everything: frontend, backend, testing, documentation, deployment. No real team works that way.

The real leverage comes when you organize AI as a team: onboarding, standard procedures, specialists, and parallel execution.

In the MCP post, I covered how to give your AI agent access to your environment. In AI gives you speed, not quality, why human judgment still matters. This post covers the missing piece: how to organize that access into a coordinated workflow.

The onboarding doc #

Every good team starts with onboarding. AI agents need the same.

Project rules #

In Claude Code, the CLAUDE.md file at the root of your project is the onboarding doc. The agent reads it every time it starts working: project structure, coding conventions, style guides, tool configurations.

But CLAUDE.md is just the entry point. You can split rules into focused files under .claude/rules/, each targeting specific parts of your codebase via glob patterns. The agent doesn’t just know your conventions, it’s constrained by them. Layer boundaries, naming patterns, dependency directions. All versioned alongside the code they protect. And since .claude/ lives in the repo, every human teammate gets the same setup when they join the project.

modules/*/Domain/**/*.php: No framework imports, no infrastructure dependencies, only plain PHP.
modules/*/Infrastructure/**/*.php: Controllers stay thin, Eloquent models stay in their place.
resources/js/**/*.tsx: Component conventions, TypeScript strictness, styling patterns.

Each rule file is scoped to the files it cares about. Domain rules don’t fire when editing a controller.

Personal preferences #

There’s also a global ~/.claude/CLAUDE.md that applies across all your projects. Commit message conventions, communication style, formatting habits. The project file says how this codebase works. The global file says how I work.

A well-written CLAUDE.md is like a good onboarding doc. The better it is, the less you repeat yourself.

Standard operating procedures #

Every team has recurring workflows that live in wikis, runbooks, or someone’s head. When they live in someone’s head, they’re fragile.

Custom slash commands in .claude/commands/ turn these workflows into executable instructions. Each command is a markdown file describing a multi-step procedure. In one of my projects, every creation command starts with tests. TDD is baked into the procedure, not left to discipline.

Creation (TDD-first):

/create-module: Scaffolds a hexagonal module with domain, application, and infrastructure layers.
/create-entity: Domain entities with value objects and test files.
/create-use-case: Command/query handlers with mocked tests.
/create-page: React pages with factories and smoke tests.

Quality & workflow:

/refactor-check: Analyzes code against SOLID principles.
/test: Runs the suite with module filtering.
/fix: Auto-applies linting and static analysis corrections.
/gh-issue: From GitHub issue to implementation to PR in one command.

The key insight: commands turn tribal knowledge into executable instructions. What used to be “ask Sarah how we set up a new module” becomes a command anyone can run, human or agent.

Specialists, not generalists #

Commands are your procedures. They encode how your team does things. But there’s another layer: skills and agents.

Skills as knowledge bases #

Skills are structured knowledge the agent can draw from. In one of my projects, I have skills for SOLID principles, hexagonal architecture, TDD workflows, and React/Inertia patterns.

Rules constrain: “don’t do this, always do that.” Skills teach: “here’s the pattern, here’s why, here are the common mistakes.” Rules are guardrails. Skills are expertise.

Agents as specialized roles #

Instead of one generalist, you define specialized agents with a clear role, specific tools, and even a different model based on the complexity of their job. You don’t need your most senior architect to rename a variable.

Explorer (lightweight model): Read-only reconnaissance. Searches the codebase, finds files, understands structure. Access to read and search tools, nothing else.
Clean code reviewer (mid-tier model): Checks for SOLID violations, code smells, and naming inconsistencies. Read and grep access only.
TDD coach (mid-tier model): Guides the red-green-refactor cycle. Can edit files and run tests.
React reviewer (mid-tier model): Frontend patterns: component structure, TypeScript strictness, dark mode support, accessibility.
Domain architect (most capable model): Complex architectural decisions, module boundaries, and DDD patterns.

The right model for the right job. Fast and cheap for exploration. Capable and thorough for architecture.

Let them work together #

This is where the team metaphor becomes literal. A single agent following instructions is useful. Multiple agents working from a shared plan is a team.

Subagents vs agent teams #

Not all multi-agent setups are the same. There are two distinct coordination models, and choosing the right one matters.

Subagents run within a single session. They do focused work and report results back to the main agent. They can’t talk to each other. The main agent manages everything.

Agent teams are different. Each teammate is a fully independent Claude Code session with its own context window. They communicate through a shared mailbox, claim tasks from a shared task list, and coordinate without going through a central bottleneck.

The architecture has four components:

Team lead: the main session that creates the team and orchestrates work
Teammates: separate Claude Code instances, each owning specific tasks
Task list: shared work items with dependency tracking. Blocked tasks automatically unblock when dependencies complete
Mailbox: direct messaging between agents, including broadcasts to the entire team

Subagents are workers that report back. Agent teams are collaborators that think together.

Use subagents when only the result matters. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

Getting started with agent teams #

Agent teams are still experimental. Enable them by adding this to ~/.claude/settings.json:

{
 "env": {
 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
 }
}

Creating a team is conversational. Describe what you want: “Create an agent team to refactor the auth module. Spawn three teammates: one for backend API changes, one for frontend components, one for writing tests.” Claude sets up the task list, spawns the teammates, and coordinates their work.

You can view the team in-process (single terminal, navigate with Shift+Up/Down) or split across panes (each teammate in a separate tmux or iTerm2 window). Use Shift+Tab to activate delegate mode, which restricts the lead to coordination only.

Token consumption warning. Agent teams burn through tokens fast. Each teammate has its own context window, and every message between agents adds up. Start with research and review tasks before moving to implementation. Three teammates exploring in parallel costs roughly 3x. Make sure the parallelism pays for itself.

Teammates load your project context automatically (CLAUDE.md, MCP servers, skills) but don’t inherit the lead’s conversation history. When spawning a teammate, be specific about which files to focus on and what constraints apply. A vague spawn prompt produces vague work.

Plan first, execute after #

Good teams don’t just start coding. They discuss the approach, identify dependencies, agree on a plan. Claude Code’s plan mode works the same way.

You describe the problem. The agent explores the codebase, maps dependencies, and proposes an approach before changing anything. You approve, modify, or reject. Think first, code second.

With agent teams, plan approval lets you require teammates to design their approach before implementing. The teammate works in read-only mode until the lead approves. You can shape the lead’s criteria: “only approve plans that include test coverage” or “reject plans that modify the database schema.”

Delegate mode restricts the lead to coordination only. Without it, the lead sometimes starts implementing instead of waiting for teammates. Delegate mode keeps it focused on orchestration, not execution.

Competing hypotheses #

This is the most compelling agent-team pattern for debugging. When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. Agent teams fight this by making teammates adversarial. Each one investigates its own theory while actively trying to disprove the others.

Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators challenging each other, the theory that survives is much more likely to be the actual root cause.

Size tasks for parallel work #

Not all work benefits from parallelism. The key question: can the teammates work independently?

Too small: coordination overhead exceeds the benefit
Too large: teammates work too long without check-ins, increasing wasted effort
Just right: self-contained units that produce a clear deliverable. A function, a test file, a review

Having 5-6 tasks per teammate keeps everyone productive. Break the work so each teammate owns a different set of files. Without isolation, two teammates editing the same file leads to overwrites. Worktrees change this.

Say you’re building a new feature that touches both backend and frontend. After planning:

A backend agent scaffolds the domain layer: entities, value objects, repository interfaces, use case handlers. All following hexagonal architecture, all test-first.
A frontend agent builds the React page, components, hooks, and factories. Each follows its own rules, draws from its own skills, and operates independently.

They don’t step on each other because the plan already defined the boundaries. Clear ownership. No merge conflicts. No waiting.

Worktree isolation #

The biggest friction with parallel agents was file conflicts. Two agents editing the same file meant overwrites and lost work. Git worktrees eliminate this by giving each agent its own working copy of the repository.

Start Claude Code with --worktree to run in an isolated worktree. Multiple sessions, same repo, no clobbering. Add --tmux to launch it in its own tmux session.

claude --worktree --tmux

Subagents support worktrees too. Ask Claude to use worktrees for its agents, or set isolation: worktree in your custom agent frontmatter to make it the default.

---
isolation: worktree
---

The Desktop app has the same feature: enable worktree mode in the Code tab.

For non-git source control (Mercurial, Perforce, SVN), define worktree hooks to get the same isolation benefits without switching to git.

Worktrees turn “clear file ownership” from a planning constraint into an infrastructure guarantee. Agents can overlap on the same files without stepping on each other.

Review after execution #

After implementation, review agents take over. Instead of one reviewer catching everything, you have specialists: SOLID violations, component patterns, test quality, module boundaries.

A single agent is an assistant. Multiple agents working from a shared plan is a team.

You are still the lead #

No matter how well configured, the agents work for you. You set the standards, write the rules, review the plans, and approve the output before it ships. You can message any teammate mid-work to redirect their approach or add constraints. If someone’s heading down the wrong path, you intervene directly.

As I wrote in AI gives you speed, not quality, the code the agent produces is your responsibility. Agents still make mistakes, context windows have limits, and coordination isn’t perfect. More parallelism without oversight is just more chaos, faster.

Quality gates #

Hooks and git hooks act as the final safety net. In my setup, nothing gets committed unless the full suite is green and coverage is above 90%. The agent doesn’t get to skip this. Neither does anyone else.

Agent teams add their own hooks: TeammateIdle keeps idle teammates working, TaskCompleted prevents premature task completion. Automated policies no team member can bypass.

Git hooks run linters, static analysis, and tests before every commit. Claude Code adds its own hooks (.claude/hooks/): shell commands that trigger on agent events like tool calls or file writes.

.claude/settings.json controls what agents can execute. Whitelist specific tools and commands, deny destructive operations. You control not just what agents know (rules, skills) but what they can do (permissions). Rules set the culture. Permissions set the boundaries.

The foundation matters #

The agents will help you get there faster, but “there” has to be well-defined. If you don’t know what hexagonal architecture looks like, agents won’t discover it for you.

You don’t build all of this on day one. You start with a CLAUDE.md. Then you notice you’re repeating instructions, so you write a command. An agent breaks a convention, so you add a rule. Reviews take too long, so you create a reviewer agent. The setup grows organically from real friction, not from upfront design. Each addition solves a problem you actually had. Same with agent teams: start with tasks that don’t require writing code. Review a PR from multiple angles, research a library, investigate a bug. Learn the coordination model before throwing parallel implementation at it.

If you want a starting point, I put together laravel-claude-toolkit: a Laravel starter kit with rules, commands, skills, agents, hooks, and permissions already configured. Use it as a reference or fork it for your own setup.

You’re not just using AI. You’re building a team. And like any team, the quality of its output reflects the quality of its leadership.

Resources #

Claude Code | claude.com
Claude Code: Agent Teams | claude.com
Claude Code Tips: Workflow Boosters | rfrolov.me

MCP: Giving Your AI Agent the Right Context

2026-01-11T00:00:00+00:00

Modern AI coding assistants are remarkably good at understanding context. Models like Claude Opus with large context windows (~200k tokens) can hold substantial portions of your codebase in mind, reason about architecture, and maintain coherence across long conversations. Not the entire project for large codebases, but enough to work effectively.

But understanding isn’t the same as access.

The AI can reason about your database schema if you paste it. It can suggest changes to files you share. It knows patterns from code you show it. The limitation isn’t intelligence. It’s reach.

That’s where MCP comes in.

What MCP enables #

Modern AI can understand your codebase when you share it. But understanding and acting are different things.

Many IDE-integrated assistants like VS Code Copilot or Cursor already access your project files through their own indexing. So file access itself isn’t new. What MCP brings is standardization. Instead of each tool building its own integration, MCP provides a common protocol. You configure a server once, and any MCP-compatible client can use it. It’s portable, configurable, and extends beyond just files to databases, APIs, and custom tools.

MCP turns AI from a conversation partner into an active participant in your development environment.

With MCP, you give the AI direct access to tools and resources. It can read files, run commands, query databases, fetch documentation. The intelligence was always there. MCP gives it hands.

What MCP actually is #

MCP is a protocol, not a product. It’s an open standard that defines how AI agents can connect to external data sources and tools. Think of it as a bridge between the AI model and your development environment.

The architecture is simple: MCP servers expose capabilities, and AI clients consume them. Claude Desktop and Claude Code officially support MCP, with more tools adopting the protocol as it matures.

For example, in Claude Code you can add servers to a .mcp.json file at your project root. Claude Code reads this file when you open the project and starts the configured servers automatically:

{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
 },
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": { "GITHUB_TOKEN": "your-token" }
 },
 "postgres": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-postgres"],
 "env": { "DATABASE_URL": "postgresql://localhost/mydb" }
 }
 }
}

Each server gives the AI different capabilities:

filesystem: Read and navigate your project files. The AI can explore your codebase, check existing patterns, and understand your directory structure before suggesting changes.
github: Access issues, pull requests, and repository metadata. Ask the AI to summarize open issues, check PR comments, or understand what your team is working on.
postgres: Query your database directly. The AI can inspect your schema, run read queries, and understand your data model without you copying table definitions.

Different tools, same protocol. You configure once, and any MCP-compatible client can use these servers.

Where MCP shines #

Working with your codebase #

The most immediate benefit is filesystem access. The AI can navigate your project, read source files, understand your directory structure. When it suggests code, it can check existing patterns first.

Git integration takes this further. The AI can see your commit history, understand what changed recently, and suggest modifications that align with how your codebase evolves.

Database schema access means the AI understands your data model. No more explaining table relationships or column types. It sees the structure and generates queries that actually work.

Documentation and knowledge #

Connect your internal documentation and the AI becomes aware of your team’s decisions. API specifications, architecture documents, coding guidelines. All available as context.

This is where MCP starts feeling different. The AI isn’t just generating generic code anymore. It’s generating code that fits your project.

The best AI assistance comes from understanding not just what you’re building, but how your team builds it.

External integrations #

GitHub integration means the AI can read issues, understand PR discussions, and see the broader context of what your team is working on. Slack or other communication tools can provide even more context about ongoing decisions.

Custom integrations let you connect internal tools specific to your workflow. The protocol is extensible by design.

Using MCP effectively #

MCP amplifies whatever it connects to. If your documentation is outdated, the AI will use outdated information. If your codebase is messy, the AI will learn messy patterns.

This is the mirror effect I mentioned in AI gives you speed, not quality. The AI reflects the context you give it. Good context produces useful output. Bad context produces confident-sounding garbage.

Giving AI access to your codebase doesn’t replace your responsibility to maintain it. It makes good hygiene more valuable.

A few practices that help:

Connect only what the AI needs. More context isn’t always better. Focused context is better.
Keep your documentation current. If the AI reads your docs, those docs matter more than before.
Review your MCP configuration periodically. As your project evolves, so should your context setup.
Start small. One or two servers. See what works. Expand from there.

Security matters too. Be intentional about what you expose. MCP servers can access sensitive information. Treat them like any other access control decision.

What comes next #

MCP is the foundation. But the ecosystem is building on top of it.

Agentic workflows. Tools like Claude Code and Cursor now run in “agent mode” where the AI autonomously plans and executes multi-step tasks. It reads files, makes changes, runs tests, fixes errors. MCP servers are the hands. The agent loop is the brain deciding what to do next.

Skills and custom commands. Claude Code introduced skills. Custom slash commands that chain MCP tools into reusable workflows. /deploy, /test, /review. You define them once, and they become part of your development toolkit.

A2A Protocol. Google’s Agent-to-Agent protocol. While MCP connects AI to tools, A2A connects AI agents to each other. Multiple specialized agents collaborating on complex tasks. One agent writes code, another reviews it, a third runs tests.

The pattern is clear: AI is moving from assistant to collaborator. From answering questions to executing workflows. MCP gave AI access to your environment. What’s next is AI that knows how to use that access autonomously.

The question is shifting from “what can AI access?” to “what should AI decide on its own?”

Human judgment doesn’t disappear. It moves upstream. Instead of reviewing every line the AI writes, we design the context and boundaries that shape what it produces.

That’s still our job. And it’s a job worth doing well.

AI Gives You Speed, Not Quality

2025-10-10T00:00:00+00:00

I’ve been using AI coding assistants extensively: ChatGPT, Codex, Claude with Sonnet and Opus. They’re incredibly helpful. They give you speed like nothing else.

But speed isn’t quality.

The vibe-coding trap #

AI models are excellent at imitating their surroundings. Give them context, and they’ll do whatever it takes to complete the task. This has become known as “vibe-coding”: you describe what you want, and the AI produces something that works. Fast.

The problem? AI will happily generate messy code if that’s what gets the job done. It doesn’t care about maintainability. It doesn’t think about what happens when requirements change next month. It just produces output.

AI is a mirror that reflects the context you give it. If your codebase is messy, it will generate more mess. If your prompts are vague, it will make assumptions.

Without careful guidance, you end up with patches on top of patches. Freshly created legacy code. A codebase where every change feels risky and the team spends more time fighting the code than building features.

The art of asking #

Remember Stack Overflow? Google searches that led you to forum threads from 2011 where someone had the exact same problem?

Ten years ago, being a developer meant learning how to ask good questions. You’d craft your Stack Overflow post carefully: describe the problem, show what you tried, explain what you expected versus what happened. If your question was vague or lazy, the community would let you know. Sometimes harshly.

But that friction taught us something valuable: the quality of your answer depends on the quality of your question.

The same principle applies to AI. A vague prompt gets a vague response. A well-structured prompt with clear context, constraints, and examples gets something useful. The skill of formulating good questions didn’t become obsolete. It became more important.

Learning to prompt AI effectively is the modern equivalent of learning to search Google and ask Stack Overflow. The developers who master this will get better results.

Even when AI gives you a fast, impressive-looking answer, never accept code you don’t fully understand. It’s tempting. The response appears in seconds, it looks professional, it might even work. But if you can’t explain what it does and why, you’re planting a time bomb in your codebase. And when it breaks at 2am, you’ll be debugging code you didn’t write with no mental model of why it exists.

Challenge the output. Ask: “Can you simplify this?” or “Is there boilerplate here we can remove?” AI’s default is to add, not to improve. It will generate abstractions, helper functions, and patterns you didn’t ask for. It won’t refactor unless you tell it to. Push back.

This is especially critical with tests. Ask AI to generate tests and you’ll often get tests that mirror implementation details rather than behavior. They’ll break the moment you refactor, even if the logic stays the same. If you want tests that verify behavior, you need to explicitly say so. AI won’t make that choice for you.

Don’t be seduced by speed. Sometimes, a fast answer you don’t understand is worse than a slow answer you do.

The human factor #

AI can write code fast, but it can’t understand overall architecture. It doesn’t know why certain decisions were made months ago. It can’t see the bigger picture of where the product is heading. It only sees what you show it, making local decisions without understanding global implications. That’s our job.

As I explored in different beliefs about software quality, teams often have varying standards for what “good enough” means. When you add AI to the mix, maintaining that shared understanding becomes even more critical. The AI doesn’t share your team’s values. It just generates code.

The discipline to maintain clean architecture, to say “no” to quick hacks, to refactor before things get worse. That’s uniquely human.

Books like Clean Code and Clean Architecture aren’t less relevant in the AI age. They’re more relevant. They help you spot when AI is heading in the wrong direction.

Collaboration over automation #

There’s something else AI can’t replace: the team.

A conversation with a colleague about “should we extract this into a service?” often leads to insights that no AI prompt would surface. That back-and-forth, the pushback, the “what if we tried this instead”. That’s where real understanding happens.

Extreme Programming Explained emphasizes practices like pair programming and collective code ownership for good reason. These aren’t inefficiencies to be automated away. They’re how teams build quality into their process.

When you skip the human discussion and just let AI generate solutions, you lose the opportunity to learn, to challenge assumptions, and to grow as a team.

You own the code #

When AI writes code and you commit it, review it, approve it, merge it, and deploy it, it’s your code. You can’t blame the AI when something breaks in production. You can’t point at Claude or Copilot when the architecture becomes unmaintainable.

As I wrote about the art of testing, quality is a choice we make at every step. Every commit is a decision. Every review is an opportunity to catch problems. Every merge is an endorsement of the code’s quality.

We are the ultimate responsible party for the code AI writes. The commit, the review, the approval, the merge, the deploy. That’s all us.

Moving fast in the wrong direction just gets you lost faster. Lines of code appearing on screen isn’t progress. The value we bring as developers isn’t typing speed. Our value is in understanding where we’re going, maintaining discipline over chaos, and ensuring that the code we ship today doesn’t become tomorrow’s nightmare.

Use AI. Embrace the speed. But never forget: you’re the one steering. If you let go of the wheel, you’ll end up in a pile of unmaintainable code faster than you expected.

And when that happens, there’s no one else to blame.