Visual field guides
Each series is consolidated into a single illustrated guide, built to be handed to a team rather than read once.
- RAG · The Visual Field Guide Why retrieval exists, how embeddings and BM25 actually work, chunking, reranking and ANN indexes.
- Managed Agents · The Visual Field Guide Orchestration, parent and child isolation, parallelism, model matching, cost, and when not to reach for an agent.
- Evals · The Visual Field Guide What evals actually are, the four questions people conflate, how teams build them, when to run them, and which frameworks are worth the trouble.
- The MCP Knowledgebase Model Context Protocol explained: architecture, primitives, call flow, server design and security.
- Anatomy of an AI Coding Agent An eight-part dissection of the OpenAI Codex CLI: architecture, protocols, prompt assembly, sandboxing, tools and safety.
- Claude Code Plugins · The Definitive Visual Guide Skills, agents, hooks, MCP and LSP servers, monitors, security and workflow automation.
Retrieval and RAG
Companion guide: RAG field guide
-
Why RAG Exists: The Context Window Is a Red Herring
The standard answer goes like this. The model has a limited context window; your data is bigger than that window, so you retrieve the relevant parts instead of sending everything. It is not wrong. It…
-
How Chunking Works: Why Your Best Document Never Gets Retrieved
Chunking gets treated as a formatting decision. Cut documents into pieces because whole documents are too big to send to the model; pick a size, add some overlap, move on. It looks like the least inte…
-
Hybrid Retrieval: What Embeddings Cannot See
Picture the query. Something like ERR_4021, pasted straight in. Semantic search returns three documents. "Troubleshooting common errors." "What to do when something fails." "Error handling best practi…
-
When Not to Use RAG: You Are Sizing It Off the Wrong Number
Here is a scenario that sounds like an obvious retrieval problem. Eight thousand contracts, around eighty pages each. Roughly half a billion tokens. Users asking questions about them all day. Nothing…
-
How RAG Fails: Eleven Modes, One Symptom
Consider a question that looks perfectly reasonable to ask a retrieval system: how many enterprise customers churned in Q2? It answers seven and cites seven sources. Check them. Every citation resolve…
Agents and evaluation
Companion guides: Managed Agents field guide and Evals field guide
-
The Scariest AI Agent Failure Is the One That Looks Like Success
Everyone designs for the crash. Almost nobody designs for the lie. After running multi-agent pipelines in production for a while, I've come to sort failures into three kinds. Only one of them announce…
-
Every Multi-Agent System I've Studied Is One of These Five Designs
Somewhere along the way, while reading about and building multi-agent systems, I noticed the variety is mostly an illusion. Underneath, nearly everything is one of five shapes, sometimes combined. Lea…
-
I Assumed Multi-Agent Meant 4x the Cost. The Math Said Otherwise.
When I first sketched a multi-agent redesign of one of my pipelines, I did the obvious math and almost abandoned the idea. The pipeline evaluates items in bulk. Say a thousand items. The single-agent…
-
The One Sentence That Explains Every Multi-Agent Failure I've Seen
A child agent knows only what the parent writes into its prompt. That's the sentence. Everything else in this article is just me convincing you to take it as seriously as it deserves. The bug that tau…
-
Your AI Agent Has a Ceiling. Here's Where It Is.
You might have spent a good part of this year building AI solutions, and then kept running into the same wall. Not a bug. Not a bad prompt. A wall that's built into the architecture itself. Let me wal…
Model Context Protocol
Companion guide: The MCP Knowledgebase
-
What Is MCP and Why Does It Exist?
MCP stands for Model Context Protocol. It is an open protocol that gives AI applications a standard way to connect with tools, data, and reusable prompts. The simplest way to think about it: MCP is a…
-
MCP Architecture, Primitives, and Call Flow
MCP becomes much easier once you separate the three ideas: The roles in the system The capabilities a server exposes The lifecycle of a request Together, these form the mental model you need before bu…
-
MCP Is Not Just REST for AI
One of the fastest ways to misunderstand MCP is to describe it as "REST for AI agents." That sounds convenient, but it misses the point. REST and MCP solve different problems for different consumers.…
-
MCP Security Risks You Should Understand
MCP servers sit between agents and real systems. That makes them powerful. It also makes them sensitive. If an MCP server can read private data, create tickets, update records, trigger workflows, or m…
-
Best Practices for Building MCP Servers
Building a basic MCP server can be quick. Building one that agents can use safely and effectively takes design. The biggest mistake is treating MCP as an automatic export of your existing API. A good…
Inside Codex CLI, an eight-part series
Companion guide: Anatomy of an AI Coding Agent
-
The 10,000-Foot View: What Is Codex CLI and Why Should You Care?
The Very Smart Intern in a Padded Room Imagine you hire an incredibly talented software engineer. They understand every programming language. They can design systems, write tests, debug issues, and ev…
-
The Nervous System: How Components Talk
Last time, we saw the 10,000-foot view of Codex: the orchestrator that lets you command an AI agent to build, debug, and explore code. We saw it as a black box with users on one end and executed comma…
-
The Brain: Inside the Core Engine
Part 3 of "Anatomy of an AI Coding Agent: Dissecting the OpenAI Codex CLI" We've journeyed from the 10,000-foot view of Codex's architecture down to the nervous system that carries signals between com…
-
The Vault: How Every Command Runs in a Sandbox
We've traced the journey from protocol to nervous system to the beating heart of the orchestrator. Commands arrive. The engine accepts them. But here's the sacred truth that separates a useful AI agen…
-
Part 5: Four Windows Into One Brain
TUI, Exec, App Server, and MCP Server
Welcome back to our deep dive into Codex, the OpenAI CLI agent that's reshaping how developers interact with AI. In Part 4, we explored how Codex manages execution—sandboxes, approvals, and rollback.…
-
The Swiss Army Knife: MCP, Tools, and the Plugin Ecosystem
Welcome back to our journey through Codex's architecture. In Part 5, we explored how Codex manifests in four different frontends—TUI, exec, app-server, MCP server. But we only touched the surface of M…
-
Part 7: The Safety Net
Hooks, Policies, and the Approval Chain Welcome to Part 7 of our journey into Codex's architecture. We've explored the brain, the nervous system, the vaults, the frontends, and the plugin ecosystem. N…
-
Building on the Giant: SDKs, APIs, and What's Next
Standing on the Shoulders of Giants We've climbed seven mountains together. In Article 1, we saw the 10,000-foot view of the four buildings that make up Codex. In Article 2, we traced the nervous syst…
Agent tooling and team practice
Companion guide: Claude Code Plugins guide
-
Stop re-explaining your stack to your AI every morning
You onboard a new engineer once. You walk them through the architecture, the folder layout, the three things that look weird but exist for a reason, and the rule about never putting money in a float.…
-
Your team's standards keep getting ignored. Hooks fix that for good.
Every team has a style guide nobody fully reads and a linter someone quietly disables when it gets annoying. You write the conventions down. You mention them in code review. And they still erode, one…
-
The most important code in your plugin isn't code
You can write a genuinely useful tool, wire it up perfectly, and then watch your AI assistant never reach for it. You ask it to do exactly the thing your tool was built for, and it improvises somethin…
-
A plugin you didn't audit is a plugin you don't trust
Installing a plugin is one of the most trusting things you do all day, and you probably do it without reading a single line of what's inside. Think about what an install actually means. The moment a p…
-
How to turn a 20-minute chore into a 2-minute command
Picture the task you have done so many times, your hands move on their own. The PR review. The pre-deploy checklist. The support-ticket triage. None of it is hard. All of it is friction, repeated, for…
-
SprintFoundry now supports Agent Sandboxes
Most people think the hard part of AI agents is the model. I don’t. The hard part is giving the agent a real place to work. That’s why I’m excited to share that SprintFoundry now supports Agent Sandbo…