Forem: Simon Boudrias

[Boost]

Simon Boudrias — Thu, 12 Feb 2026 16:26:46 +0000

🧑‍💻 How to remain relevant in this AI era?

Yoann Moinet for Datadog Frontend Dev ・ Feb 12

Generic Sub-Agents Are... Good?

Simon Boudrias — Fri, 31 Oct 2025 14:24:11 +0000

This week, I’m sharing something more practical!

I’ve been a fan of Claude code sub-agents for a while. I mostly used them to split up context-heavy processes into smaller, focused agents.

Recently, while chatting with my colleague Brad Carter, he mentioned the idea of replicating the different personas inside a startup — having different AI roles work together. It sounded odd at first, but I had to try it for myself.

After experimenting with a few personas, one combination stood out: a software engineer and a code reviewer.

I think the magic comes from how the two sub-agents collaborate — the reviewer always starts with a fresh perspective. This helps catch any hallucinations or deviations from the plan early on, preventing them from spreading through an entire coding session.

Setting Up Your Agents

I’ve published the agents in my Claude marketplace for easy access. You can also copy-paste them freely.

claude plugin marketplace add https://github.com/SBoudrias/claude-marketplace

Then open Claude, run /plugin, and select Browse and install plugins. Choose the marketplace, then install startup-subagents.

How to Use

I’ve included a helper command, but it’s really just a one-liner prompt:

Orchestrate work between the senior-software-engineer and the code-reviewer to implement [...fill in the blank!]

In practice, I often ask Claude to help me draft a technical plan inside a file like PLAN.md, then run:

/orchestrate @PLAN.md

For smaller tasks, I just run something inline, like:

/orchestrate fix failing CI on the PR

Conclusion

That’s it — simple and powerful. Give it a shot and let me know how it goes!

If you’re still struggling to get high-quality code from AI agents, check out my previous post. The most common mistake I see is delegating the thinking. Once you describe how the code should be implemented, you’ll realize the AI is there to assist — but you’re still in the driver’s seat.

Steering AI Agents in Monorepos with AGENTS.md

Simon Boudrias — Fri, 26 Sep 2025 19:11:37 +0000

Why Steering Documents Matter

A well-maintained AGENTS.md is the contract between your codebase and the agent ecosystem. It answers:

What can I ask this agent to do here?
What tools, conventions, or workflows are in scope?

A good baseline of steering documents makes AI more predictable and reliable. Hinting it to follow your patterns, understands your architecture, and generates code that fits your codebase. It doesn't replace good AI practices, but it improves the OOTB experience.

Remember it is written for AI agents, not human. Keep them concise and to the point. For example, see the GPT5-codex prompting guide and the terseness of the prompts. Characters add to an agent context window, so terseness allow them to do more.

How to Test Your Steering Docs

Testing steering documents is similar to testing an onboarding guide. You need to walk through it step by step.

Create a collection of example prompts.

Think of all the tasks an engineer might do inside your monorepo, make sure you have one or 2 example prompts per task.
Example: “Migrate an email template to our new framework. Here's the previous code: [...]”
Store them somewhere durable.

A shared Google Doc or Confluence page works fine—these are lightweight, editable, and accessible.
Run the prompts with all your supported tools.

Try Claude Code, Cursor, Codex CLI, or whichever agents your team supports. Different agents work differently, it's best to test across.
Observe breakdowns.

Where did the agent get lost? What knowledge did it lack to properly complete the task? git reset --hard, edit your steering doc, and retry until your agent one-shot your test prompt.

This may feel simple, but simplicity is a feature. You’ll uncover real gaps faster than if you over-engineer an evaluation framework. Over time, you can start introducing automated evals—but don’t let that block you getting started.

AGENTS.md and Its Variants

Most tools today recognize AGENTS.md as a standard.

A notable exception at the time of writing is Anthropic's Claude code which only supports CLAUDE.md. (let's hope this changes soon)

To support Claude code, I recommend against a symlink. Instead I approach it like this:

echo "Read @AGENTS.md" > CLAUDE.md

I prefer this approach because it gives us the flexibility to expand it with Claude-specific features (like sub-agents.)

repo-root/
├── AGENTS.md
├── CLAUDE.md          # contains "Read @AGENTS.md"
└── src/
    └── ...

Root AGENTS.md as your router

Nested AGENTS.md are the default recommendation for monorepo. This means the closest AGENTS.md to the edited file wins, but I find this approach quite limited on its own! For one, that only work if working from a sub-folder/specific file or if a user @ reference the file manually. Doing only that:

Limits the agent access to examples/patterns in the rest of the codebase.
The user needs to know from which sub-folder to work; making discoverability harder.

We can bridge that gap with a root AGENTS.md to progressively disclose information to your agent. For example:

# Tasks

To create an email, read @emails/AGENTS.md
To create a Go service, read @go/services/AGENTS.md
To add unit tests, read @.agents/unit-tests.md

Whenever appropriate, we prefer adding documentation in an AGENTS.md contextual to a folder's content. But a general .agents/ folder to collect the other type of content is quite valuable for more generic context.

Folder structure example:

repo-root/
├── AGENTS.md
├── emails/
    └── AGENTS.md
├── go/
    └── services/
        └── AGENTS.md
└── .agents/
    └── unit-tests.md

This way, the root AGENTS.md becomes a map, pointing agents to only read the relevant document based on their task. This helps a lot managing the context window when working on longer running tasks.

What about documentation maintained elsewhere?

At a high level, there's nothing wrong referencing external documentation.

To create an email, use Atlassian MCP server to read https://...

The downside is the risk of filling the context window with documentation written with humans in mind. But because you're testing your core prompts, you'll see easily if you're causing an agent to hallucinates.

We recommend a pragmatic approach at first, and expanding later on.

Alternatively, you can ask the agent to summarize the content of the external documentation. Put the output in an AGENTS.md file, and tell the agent they can search for more information if needed at the given URL.

This will then need to be kept up to date as any documentation. And that's something we're hoping to delegate to autonomous agents soon enough...

Bring your Platform Teams along

At some point, centralized dev experience teams can’t be experts in everything. Platform and product teams must own their own steering content.

The central team provides the scaffolding (AGENTS.md, routing, shared configs).
Each partner team fills in domain-specific instructions (e.g., “how to add observability to a python backend service”).
This shifts expertise closer to where the work happens, while maintaining a consistent navigation structure.

Supporting User Customization

Not every engineer works the same way. Customization matters.

Global preferences. Example: tone, tool prioritization. Place these in ~/AGENTS.md.
User-repo-specific overrides. Example: which service they own, what's their scope, etc. Introduce AGENTS.local.md. .gitignore it. And instruct your root AGENTS.md to check it first: If present, prioritize instructions inside @AGENTS.local.md

repo-root/
├── AGENTS.md
└── AGENTS.local.md   # .gitignored, user-specific

Conclusion

Steering documents are still a pretty new territory for us. So we’re more than eager to learn from the community!

How do you structure steering docs in your monorepos?
Do you share other configs (beyond steering), when/what?
Where have you seen agents get lost most?

This space is moving fast—best practices will come from the community as much as from tools. This is only an approach, and called to evolve.

Latest post!

Simon Boudrias — Thu, 18 Sep 2025 14:21:02 +0000

AI Coding Is Boring — And What To Do About It

Simon Boudrias for Datadog Frontend Dev ・ Sep 18

#vibecoding #ai #coding #productivity

AI Coding Is Boring — And What To Do About It

Simon Boudrias — Thu, 18 Sep 2025 13:19:54 +0000

When I first tried AI coding, I was bored out of my mind. I’d type in a prompt… and think ‘guess I’ll wait?’ A minute later, some half-baked code would appear. I’d ask for a refactor. More waiting. Another tweak. More waiting. Eventually I’d close the tab and move on.

When the Magic Trick Falls Flat

The hype told us AI would be like waving a wand: type a prompt, get production-ready code. So when the output is clumsy, we don’t ask ‘What did I miss?’—we jump straight to ‘This thing is dumb.’

You’re not alone if you’ve felt that way—nearly half of developers don’t trust AI’s accuracy according to the 2025 Stack Overflow Survey.

AI is just a tool—am I the problem here?

Here’s the shift: AI isn’t magic. It’s a tool. And tools only become powerful once you learn how to use them. These days, I’ll hash out a technical plan chatting with AI—what the interfaces look like, where the code should live, how the algorithm should work. Once the plan feels solid—something the size of a PR milestone—I send it off. The agent spends twenty minutes or more grinding through implementation while I'm free to move on to something else. That’s when AI stopped boring me and started being empowering.

Are you delegating the thinking?

I'll quote my colleague Mat Brown

We shouldn’t merely give the AI a goal; we should describe the code we want to see at the level of individual functions, data structures, control flow structures, and so on. “Use detailed prompts” is commonplace advice for users of AI tools, but this goes beyond optimizing the AI’s output. Our prompts should be detailed because we shouldn’t delegate the thinking to the AI.

Tell the AI what code you want it to write. That oughta fix most concerns of code quality.

Stop Babysitting, Start Leading

Now I want to challenge you. If you’re prompting AI to refactor a few lines at a time, you’re babysitting. This is the uncanny valley you must leave!

Your goal is to get your agent to “one-shot” a large chunk of work independently over a meaningful period of time. Aim for at least 20 minutes.

If it fails? Don’t patch its mistakes, jump on git reset --hard. Do it as often as you need.

Ask yourself: what context was missing? Can I update AGENTS.md, add some rules, or just refine my prompt with more clarity? Do those edits and start over. Don't give up until that code output is close to perfection.

You'll find yourself in no time preparing much better prompts. And you'll find your agent much smarter.

Determinism Always Wins

One more tip: AI is probabilistic. Request deterministic workflows whenever you can. For example: Codemods, other AST transformation, linting rules, a small jq command or even a grep/sed combo, are predictive operations.

You can ask the agent to generate the script, review it, and then run it with confidence.

Don’t Forget the Craft

Once the AI has cranked out code that's complete and well architected, ditch the prompts and dive back into your IDE. Prompting to refactor gets you back into babysitting mode. It's slow and expensive.

At that point, edits should be minor and simple. Don't overthink it, grab that IDE, get in the flow. Use your uniquely human taste and judgement to shape the final code.

That last 10% of engineering—the craftsmanship—still belongs to us.

Your Move

Silence the hype, there's no magic. If you treat AI as a tool that gets better the more you learn to use it, you’ll find yourself less bored and more empowered. Don’t settle for babysitting. Push AI to work for you, reset when it fails and iterate until you improve. Keep the final touches for yourself; that’s where the fun lives.