![]()
It built exactly what the spec said. That was the problem.
This week’s newsletter is all about working with AI agents.
1. One Repository per Area of Work
People who run an AI agent out of one giant folder are like people who mix their work tasks with their personal diary. Everything is in there, so everything gets read.
If you use an AI agent tool like Claude Code or Codex (or Muse or GrokBot or Dots), you’ll keep running into the word “repository”. It’s just a folder with its own history, so every change made inside it is tracked. My position is that multiple repositories, one per area of work, beats out a single big one.
The reason is that your instructions file is sent along with every request. In a mixed workspace, every prompt carries rules and files that have nothing to do with the task, and Anthropic’s own guide says that large workspaces “can fill the context window with instructions and file reads unrelated to the task, costing tokens and degrading Claude’s performance”.
So list out your three to five areas of work: content, website, each client, each work project. Give each one its own folder with its own instructions file (AGENTS.md with CLAUDE.md symlinked), and run the agent inside one folder at a time. If you don’t use a terminal, you can do the same thing with one Project per area in Claude or ChatGPT.
I keep a separate repository for each app and each client project. My content repository and my website repository are separate, for example. No agent has to read unrelated material, and each project’s history stays clean.
Not everyone agrees. Some developers and business users argue that splitting repositories is “a human way of managing complexity”, and that related repositories should sit under one outer workspace. My reply is to separate by default, and when two areas really do need each other, pull the second folder in as a reference for that one task.
I cover the one-folder-per-project setup in The Complete Claude, Claude Code & AI for Work Productivity.
2. Never Feed Someone Else’s Spec Straight to an AI Builder
AI builds exactly what the document says, including its gaps and its over-complications.
I recently took a colleague’s spec for an app and gave it to an AI builder word for word. Two weeks later I had lost DAYS repairing the backend, including critical payment code that was far more complicated than it needed to be.
The main reason to slow down is that you need to understand what the output should be before you ask for it. When you gloss over a spec that you haven’t understood yet, you just don’t know what you asked for. The AI will fill every gap with its own choices, and you WILL be surprised by the result… and NOT in a good way.
You will also really struggle to review what comes back. Reviewing means comparing the work against the final vision in your head, and without that vision all you can check is that something was produced, not that it’s right.
So when someone hands you a brief or a spec, don’t paste it into an AI tool and press go. You must read it yourself. Then use the AI as your collaboration partner, and have it read the spec too, question it and propose a plan. Matt Pocock’s grill-me skill is good for this, as it has the AI interview you one question at a time until every decision in the plan is mutually agreed upon.
Ask the AI to list what is unclear, missing or contradictory, and for the simplest design that meets the goal. Take the open questions back to the author, write down in your own words what the finished result should look like and do, and only then ask it to build and review the result against that description. Or, just use grill-me repeatedly.
Every handover I get now goes through a spec clean-up and architecture step before any building starts. The same goes for any non-code knowledge work like briefs or reports.
3. Courses
I have a range of online courses that teach business people what they need to know about productivity and AI:
1. The Complete Claude, Claude Code & AI for Work Productivity
A comprehensive course taking you from beginner AI concepts like prompt and context engineering, to cutting-edge AI productivity using terminal-based AI tools like Claude Code for non-coding office work. Usable with ChatGPT, Claude, Gemini and other current LLMs.
2. The AI Agents, Automations and Agentic Workflows Guide
This non-technical course shows business people and non-coders how they can build and use AI agents in ChatGPT and Zapier.
3. The AI Playbook
This is my longer premium course on how businesses can deploy AI tools and technology across their processes and teams.
4. ChatGPT for Managers
See how AI can solve complex management challenges in less than 30 seconds. Full prompt library and examples included.
5. Next Level Productivity
A practical, straightforward course that teaches you how to achieve elite-level personal productivity in today’s constantly interrupted world.
That’s it for this week!
— Aaron