<font color="#ffff00">⚠</font> I need to restructure these to make them usable for anyone else; for now they're pretty raw and only lightly edited. Notes on this material * I primarily use Claude via Claude Code, so that’s what I focus on in this doc. Pretty much everything I say is equally applicable to other agents, but some of the specifics might vary (e.g. CLAUDE.md files might be GEMINI.md or AGENTS.md, instead). * Many of the examples I give are taken from a project I’m working on right now, the [PBE Address Book](https://github.com/fthiess/pbe-address-book). For small “vibe” projects, most of this isn’t needed. - Here are [Gemini's notes and video of the conversation with Jon and Ben](https://docs.google.com/document/d/1uNUG1sJn1ipTEVefWVg7Dd4gPmeytWXtuMgAOrvWfQk/edit?tab=t.ltcf51f0rr5f) (going through this document) - Here are the [notes and video from our second session](https://docs.google.com/document/d/1wLZmD_rRChE0TeHtkaaQklYRLleazoJgOhPPj7TLSwI/edit?tab=t.xrdsldyxpjgb) (building a checkers app). --- > [!important] TL;DR > The biggest takeaways if you don't want to read this whole doc: > - Regardless of what you think is going on inside the AI's neural nets, get yourself in the habit of thinking of it as a human senior engineer and behave toward it the way you would behave toward a human, and many other things will fall into place. Don't think of it as a "super-intelligence"; don't think of it as a "pattern-matching plagiarism machine"—think of it as a co-worker, regardless of what you *actually* think is going on inside the box. > - The AI is able, even *eager*, to have conversations with you about "meta" issues. If you're not sure what to do next, *ask it*; if you wonder why it said/did something, *ask it*. You don't understand a technology it's using, ***<u>ask it</u>***. > - AIs, like humans, can only focus effectively on a limited number of things at once. To optimize AI focus, manage the length and scope of coding sessions: keep them short and targeted at closely related issues. If context grows to more than roughly half it's theoretical maximum (1M tokens for Claude and Gemini), ask the AI to write up handoff documentation and use it to start a fresh session. > - "Vibe coding" has it's place; that place isn't where quality, maintainability, and reliability live, though. The tradeoff between vibe and engineering comes down to speed versus quality. > - The people who get the best software development results out of AIs all follow variations of a few common practices: > - Never write software using an AI chatbot interface—use a coding harness instead, like Claude Code, OpenAI Codex, or Gemini Antigravity. Software engineering isn't a conversation—it's a process with rules, steps, tools, and documentation. > - Set up a workflow for the AI to follow, using CLAUDE.md (or GEMINI.md or AGENTS.md) files and skills. You can evolve your own or use someone else's, but it needs to spell out the process, steps, and gates you want the AI to follow. > - Use Github to store the AI's work. > - Require the AI to plan work before carrying it out. > - Never use more than roughly half of the model's theoretical context window. > - Ask the AI to create, then work from, written documents: > - Spec (PRD) > - Design (Engineering and visual designs) > - Roadmap (Plan or agenda) > - Decision Log > - Issue Tracker (like Linear or GitHub Issues) > - Ask the AI to create your roadmap: a list of sessions to build your project, with a specific agenda for each, planned out so they each focus on one closely related set of design features, and sized so they won't use more than ~1/2 of the AI model's context window. > - Always have the AI write tests. > - Have the AI always run a code formatter and linter (e.g. Biome for Typescript) on any code it writes, and set the linter to flag common anti-patterns and high code complexity. > - Always use a fresh context to do code reviews. --- # Background In the early days, AI chatbots would just generate responses to your prompts. Prompt→response→prompt→response, and so on. All the responses were generated by their neural net, based on their training data. Then: * ***Reasoning*** was added to chatbots—they would talk to themselves in an internal dialog before responding to you. * Then ***tool use*** was added: the ability to do a web search to get more information, for example. * Then ***memory*** was added—they could make notes for themselves that they would pull back in later, to remember things. ## What’s an agent Agents take this platform and add a recursive Reason-Action (“ReAct”) loop: they receive input, think about it, use tools to get more information and to make changes in the world, then observe the result of those changes and take that as new input, starting the cycle again. When combined with memory and tool use, they can do very complicated things over long time horizons: *like write software*. The most popular [definition of an “agent” is from Simon Willison](https://simonwillison.net/guides/agentic-engineering-patterns/what-is-agentic-engineering/): > *...the definition I've come to accept, at least in the field of Large Language Models (LLMs) like GPT-5 and Gemini and Claude, is this one: > > **Agents run tools in a loop to achieve a goal** > > The "agent" is software that calls an LLM with your prompt and passes it a set of tool definitions, then calls any tools that the LLM requests and feeds the results back into the LLM. > > For coding agents, those tools include one that can execute code. > > You prompt the coding agent to define a goal. The agent then generates and executes code in a loop until that goal has been met. An “agent” is an LLM plus a “harness”—a piece of software that allows the LLM to make use of: * **Context** * This is what makes chatbots able to have discussions. * This is a combination of a “system prompt”, “skills”, and the entire history of your conversation so far. You can think of it as what’s on the agent’s “mind” right now. * **Reasoning** * Separate from it’s conversation with you, the LLM can have a separate “thinking” track where it talks to itself. This makes the LLM “smarter” by taking time to reason its way through things. * **Memory** * The agent writes things it wants to remember into files; it reads those files later to remember * LLMs are like the main character in the movie *Memento*: they don’t remember anything unless they write it down. And if they write it down wrong, or if someone (like you) edits what they wrote down, it changes how they act without them ever knowing someone else edited their memories. * **Tool Use** (aka “Function Calling”) * The LLM understands how to find and use tools * Search, read, and write files * Run shell commands on your computer, including installing and using software packages * Do web searches * Setup to-do lists for itself * Calculator * Monitor: wake the agent when some external event happens * Code execution * The ability to write a program into a file... and then to run that program, and return a result. * Access other systems via CLI, API, or MCP * CLI: The agent types commands to the other system by typing commands to it and reading it’s responses, the same way a user would * API: The agent has a machine-to-machine protocol interaction with the other system * MCP: The agents talks to the other system in human-readable language. MCP has been called “USB for AI”: they’re usually built on top of an existing API; they’re a way of creating a sort of self-documenting English-language API that’s particularly easy for AIs to understand and use. Once an MCP has been built for some system, any AI can use that system. * Note: Harnesses + Skills are often a more effective way to g An agent is far more capable than AI chatbots; they can can do autonomous real-world work. Harnesses are programs that run on your local machine; they provide structure and tools that turn LLMs into agents. Examples of agentic harnesses: * [Claude Code](https://claude.com/product/claude-code) (paired with Anthropic’s Claude) * [Codex](https://chatgpt.com/codex) (paired with OpenAi’s GPT) * [Antigravity](https://antigravity.google/) (paired with Google’s Gemini) There are lots of others, both open and closed source. Most can be configured to work with any LLM, but they the harness/LLM pairings that work best are the ones that were designed to work with each other. ## What is context Context is the agent’s currently-active memory and contains the full combination of everything you or it or any of it’s tools, have previously said in the session. On every “turn” in the conversation, the *entire* context gets played back through the LLM’s neural net. Your new responses, it’s responses to you, it’s internal “thinking” comments, data coming back from tools the agent uses... these all go into the context and get played back again and again... *making the context’s length grow exponentially the longer you keep talking to it.* There are several problems that start showing up as the context gets longer and longer: * The LLM’s “mind” gets fuller and fuller of stale. irrelevant, and distracting information; this makes it harder and harder for it to focus on current actual facts, and on what it’s supposed to be doing. * For reasons no one understands yet, LLMs and agents recall the *early* and *late* parts of their context really well, but their recall for the *middle* parts falls off quite a bit. As the total context gets longer and longer, more and more of the “meat” of the session falls into the “middle”. * LLMs have a maximum “context window”; usually something between 100K and 1M “tokens” (tokens aren’t words, but for current purposes, assume they are, so 100K is a few hundred pages, and 1M is a few thousand pages). When the context window overflows, the oldest stuff falls off the edge and is lost—the knowledge just disappears from the model’s “mind”, which has a dramatic effect on the quality of it’s thinking. * Harnesses are aware of how full the context is getting, and when it crosses a certain threshold, they will “compact” the context by running another LLM on it to weed out unimportant details and summarize others, thus opening up more room in the context window for new discussion. * Imagine what would happen to you if someone did this to your working memory... you’d be able to keep functioning, but some lines of thought would be... different... and some things would just seem... off, in ways you couldn’t place. That’s what happens to LLMs when their context is compacted, too. Bottom line: *using more than ~half of your context window is bad* and if you do so your agent’s judgement will start slipping. Lesson: for best results, keep your sessions as short and focused as you can. If in doubt, ask Claude if it advises switching to a fresh context; it has good judgment on this! If you're in the middle of something and it's time to switch, ask it to write a handoff document to get the next session started. ## Vibe coding versus engineering The definition of “vibe coding” from [the guy who first described it and named it](https://xcancel.com/karpathy/status/1886192184808149383?lang=en), Andrej Karpathy: > *There's a new kind of coding I call "vibe coding", where you fully give in to the vibes, embrace exponentials, and forget that the code even exists. It's possible because the LLMs... are getting too good... I ask for the dumbest things like "decrease the padding on the sidebar by half" because I'm too lazy to find it. I "Accept All" always, I don't read the diffs anymore. When I get error messages I just copy paste them in with no comment, usually that fixes it. The code grows beyond my usual comprehension, I'd have to really read through it for a while. Sometimes the LLMs can't fix a bug so I just work around it or ask for random changes until it goes away. It's not too bad for throwaway weekend projects, but still quite amusing. I'm building a project or webapp, but it's not really coding - I just see stuff, say stuff, run stuff, and copy paste stuff, and it mostly works.* A key difference between vibe coding and engineering: *vibe coded software will quickly and easily surpass your ability to understand what the code is doing; engineered software won’t*. For some use cases, you don’t need to understand how the code works, but for others you do. Vibe coding is all you need for throw-away one-use programs, simple apps you’ll be the only user of, and quick prototypes and demos. Vibe coding doesn’t require any knowledge of software technology or engineering; you rely on the agent being smart enough to know what to do. For engineered projects, you *do* need have a technical background sufficient to set up a solid workflow and to be able to understand and approve the decisions the agent makes, and understand how they fit into the overall architecture of your system. Good news, though: you can ask your agent to explain things you don’t understand, at whatever level you want, and it’s very happy to answer all your questions before moving on. So you don’t need to understand everything when you start an engineered project... but you do need to be willing to learn it as you go. For vibe coded projects, you only need “Level 1” in this document. For projects that are worth doing properly, you need Level 2, and if they’re big, Level 3. ## Markdown “Markdown” is a way of including formatting in text documents that’s easy to create and read for both humans and computers. It let’s you easily do bold, italics, headings, lists, tables, and much more. LLMs *love* Markdown and use it *everywhere*. It’s also used by Github, Obsidian, and lots of other tools. Google Docs can be set to copy/paste Markdown to and from itself. All the documents talked about here are actually in Markdown. Most apps will actually format it into nice-looking text so you don’t see the Markdown code, but it’s simple to learn and use. It’s worth [learning the basics](https://www.markdownguide.org/) because you’ll see it everywhere. ## Token Usage Don’t worry about what a “token” actually is; just realize that information fed into an LLM gets converted into tokens, with most words being 1-2 tokens. The important thing is that you either get charged for LLM usage by the token (if you’re accessing the LLM via API) or you get a token “budget” (if you’re on a monthly plan). Monthly plan budgets have two levels (Anthropic, Google, and OpenAI all use the same structure): * A 5-hour limit: there’s a budget for how many tokens you can use in a five hour period. The 5-hour period starts when you make your first request and ends 5 hours later; a subsequent period starts when you make your next request after the expiration of the previous 5-hour window. * A weekly limit: works just like the 5-hour limit, but with a much higher budget amount and across a 7-day period. When you exhaust your budget at either level, you either need to stop working until the end of the budget period, or you can keep working if you pay for the excess tokens at the API rate—which is *much* more expensive. # How to use a coding agent effectively ## Level 1: The basics * The best agentic engineering tools right now (July, 2026) are Anthropic’s Claude Code and OpenAI’s Codex, with Google Antigravity close behind them. Microsoft’s CoPilot and xAI’s Grok are non-starters. * My advice: pick Claude, Codex, or Anitgravity and focus your energy on the one you choose; don’t get distracted by the “latest shiny thing” every week. * My choice: Claude. Claude is consistently the best, focuses and puts the most investment into their software development products, and, unlike OpenAI, is already profitable. Also: Claude and Gemini’s context windows are 1M tokens, but OpenAI’s is only about 200K. * Use the combination of LLM and harness from the supplier you choose; they were designed to work together. * You *can* use Codex with Claude, or Antigravity with GPT... but why would you? * There are also open source harnesses, like OpenCode and Pi... but they’re not a good or well-supported as the commercial ones. * Don’t use the free service—it’s worth paying for a plan. Anthropic, OpenAI, and Google all have more-or-less the same plan structures and pricings, although Google’s is attractive because they throw in a lot of premium Google services at no extra cost. * Plan size: depends on how much you’ll be using it. They range from $20/month to $200/month. $20/month is enough for most people, but you may find you need to pause work sometimes because you’ve spent your token budget and need to wait for it to reset. * Use the Claude Desktop app, not claude.ai web interface, nor the Claude Code TUI. They have most of the same capabilities, but the desktop app is much friendlier. * Use Claude Code, not the chat interface * Claude Code is designed for writing software on your PC; it has access to everything you’d have access to, and has powerful tools for working with code. * It has different modes: Manual, Plan, Auto, Bypass, etc. * I recommend Auto for everything; it’s like Murderbot’s “governor module”. * Claude Cowork is another option; it is designed for non-technical people and work, so it has more guardrails and fewer tools. * Never never never use the chat interface for writing code: you lose the harness, which is the thing that makes coding work so well. * Single most important thing: **Short, focused sessions** * Keep them short (< 50-60% of total context limit) * Keep them focused on one thing * Curate their context to keep unnecessary distractions out * When chatting with Claude, don’t do lots of quick back-and-forths; try to put everything in a single prompt and let it respond all at once. It’s smart enough to keep up, and it greatly reduces token usage. * Use the right model (Haiku, Sonnet, Opus, Fable) and thinking depth for the task * Keep an eye on context and usage as you work (lower right corner) * *Always* have Claude propose plan first, with an approval checkpoint for you to review, before executing * Always give Claude a way to verify its results (e.g. unit or e2e tests) * Tell Claude to check, rather than rely on its own knowledge ## Level 2: Development workflow “Workflow” is the methodology you use on a project across sessions, as well as within sessions. It’s exactly the same thing, for the same reasons, as you’d have a team of human software engineers have a team workflow or SDLC (Software Development Lifecycle). At the top level, “waterfall” and “agile” are shapes for workflows; elements you might find in them include TDD (Test-Driven Development), SDD (Spec-Driven Development), phase gates, unit tests, integration tests, bug triage processes, work scheduling, and more. [Here’s my current workflow](https://github.com/fthiess/claude-skills/blob/main/dev-workflow/SKILL.md), documented as a Claude “skill” that’s reusable across projects. Just as with human developers, there’s not one “correct” workflow; it depends on how involved you want to be, how much you trust your AI, what the project is and how it will be used, the technologies you’re using, and much more. Claude can help you define and evolve your workflow—just ask it to help you set one up, and periodically ask it how you could improve it... then ask it to implement the recommendations you like. ### Workflow tips * Don’t rely on Claude’s built-in memory. For substantial work, use a highly structured set of project docs: * A spec * Same as a Product Requirements Document (PRD): from a product perspective, what are you trying to build? * The foundation of Spec-Driven Development (SDD) * Input: explain to Claude what you want (I do this by writing a “seed” document, but you can do it interactively, too), and tell it to interview you in depth to flesh out the specification. * Mine is called [PRD.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/PRD.md) * A design * The engineering details of how the spec will be realized, in full technical detail * The input for this is the spec * Choice of programming language: only use languages Claude has lots of training data on—which is most of the popular ones. It may have trouble with niche languages. * Run it through *adversarial* design reviews and have Claude triage and incorporate the reviewers’ feedback * Each implementation session will look back at this to get the technical details of what it’s supposed to do. * I have three: [ENGINEERING-DESIGN.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/ENGINEERING-DESIGN.md), [DATABASE-SCHEMA.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/DATABASE-SCHEMA.md), and [API-SPEC.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/API-SPEC.md) (I split them because they’re pretty large, and different phases of coding work only need to look at these individually, keeping the context impact lower... and because it’s how Claude recommended doing it). * A roadmap * The project management plan: phases, broken down into sessions and sub-sessions based on focus and complexity. Each defines what is to be accomplished and what “done” looks like (i.e. exit gate criteria) * Have Claude update it as sessions are completed, and as new sessions are added. * Always start new sessions by pointing it at the roadmap so it can see where it’s at and what needs to be done. * Some people have a separate “project state” document; for me project state is included in the roadmap. * Mine is [CODING-PROJECT-PLAN.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/CODING-PROJECT-PLAN.md), but * A decision log * An append-only record of key decisions, with “this supersedes A”/”this is superseded by Y” chains. * This reminds Claude why actions were taken, what alternatives were already considered, what landmines were found, etc. * Sometimes called an ADR (“Architectural Decision Register”). * Mine is [DECSIONS.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/DECISIONS.md); it’s gotten so big it has its own index to help Claude find things in it: [DECISIONS-INDEX.md](https://github.com/fthiess/pbe-address-book/blob/main/docs/initial-build/DECISIONS-INDEX.md). * An issue tracker * Quicker and simpler than constantly updating the roadmap for every bug and feature idea * Any work that’s not being handled immediately gets a ticket * I use [Linear](https://linear.app/) for this, but there are others, like [Plane](https://plane.so/) and [Github Issues](https://github.com/features/issues). Look at their free plans and pick the one that fits you best * Use both personal- and project-level CLAUDE.md * Personal: What Claude needs to know about how you like to work * Project: Non-obvious information about the project that would be helpful to Claude; like a “start here” first-day document for a new engineer on the team. [Here’s the one for my Address Book project](https://github.com/fthiess/pbe-address-book/blob/main/CLAUDE.md). * Don’t make CLAUDE.md files too long; put detailed information in other files, and put pointers to those files in CLAUDE.md, so CLAUDE can find and read them if it needs to. * A good pattern to use: adversarial reviews—have separate agents, in clean contexts and instructions to find problems, review the work your primary agent has done with fresh eyes. * `/review` has the current agent review its own work—not an adversarial review! * `/code-review` has the current agent spin up sub-agents to review it’s work with fresh eyes from different perspectives—this *is* an adversarial review. * If you develop a workflow that you want to share across projects, have Claude help you turn what you’re doing into a “skill”. [Here’s my dev-workflow](https://github.com/fthiess/pbe-address-book/blob/main/.claude/skills/dev-workflow/SKILL.md) skill that spells out my workflow. * Don’t worry if some of the docs I’m sharing look scary: ***Claude will write all these for you***—you just need to tell it what you want and/or show it examples by pointing it to actual sessions you’ve worked with it on in the past. ### Skills/Plugins for Software Development Workflow These are skill packages that teach Claude how to use modern software engineering best practices: - Superpowers: https://github.com/obra/superpowers - Agent Skills: https://github.com/addyosmani/agent-skills - Conductor: https://github.com/gemini-cli-extensions/conductor You don’t need any of these; Level 1 + Level 2 + Level 3 above already cover all the same things, but using these can be a short-cut to getting Claude started working the way you want. Consider starting with skills like these and then customizing them to how you like operating. When you have a good workflow that you’re happy with, ask Claude to turn it into a skill of your own so you don’t need to keep guiding it’s steps ([this is mine](https://github.com/fthiess/claude-skills/blob/main/dev-workflow/SKILL.md)). You can also ask Claude to compare what you’re doing with those skill packages listed above and to give you suggestions for things you might want to add to your own skill. ## Level 3: Software engineering * Use Git and Github * Git is a deep, scarry rabbit hole all of it’s own... it’s worth learning, but you don’t need to learn it now, or all at once—Claude can do it all for you, if you ask it to. * Always do design reviews on your main design * Just tell Claude you want “fresh-context adversarial design reviews” covering security, privacy, operations & reliability, plus a broad structural, completeness & consistency review, all run by the most powerful model at the deepest thinking level, and it will manage the process for you. * Always have Claude run `/code-review` on anything non-trivial * Always require Claude to write unit tests for anything non-trivial * Have Claude use a linter, a formatter, and static analyzers * Have Claude to setup CI/CD for substantial projects * Enforces discipline: tests are run on every merge, every merge is pushed into production, all automatically * Never indefinitely defer work; “if it will *ever* be worth doing, it’s worth doing *now*” * AI changed the cost/benefit curve—there’s no longer any justification for allowing tech debt to accrue # Useful tools * Claude itself is great at answering “meta” questions about how it works, why it did things a certain way—it’s a powerful way to learn what it’s actually doing and how to use it better. Ask it anything! * `/insight` * Claude looks at how you’ve used Claude code and creates a detailed report with suggestions about how you can use it more effectively. Genuinely useful for understanding how to level-up your game. * `/doctor` * Has Claude analyze your CLAUDE.md files and skills and recommend changes to improve things.