Chemaclass - developer-tools

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.

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.