Granularity in Agentic SDLC

While breaking up tasks is good for AI, there is a limit beyond which it becomes not just pointless, but begins to severely hurt you.

We use a monorepo setup with tens of services. Service-, directory-, language-, and library-scoped AGENTS.md files, tons of skills. Agentically clean, no?

We had to add one service that would require integration with more internal services than anything we'd built before. I had the engineer who wrote the spec break it up into multiple tasks. The goal was to have reviewable, bite-sized PRs so that when the agent implemented them, we could clearly understand what it did in each PR.

He broke this service down into about 10 tasks. I looked at each and realised it wasn't granular enough. I had my agent break it down further with the following rules:

• Each PR should touch no more than 20 files. If it does, it should be broken up into different tasks.
• The exception to this rule is the scaffolding of a dependent service, an internal library, or an auto-generated client from an OpenAPI spec.
• Each PR should touch only one service, except where it's absolutely necessary for two services to evolve together.

This sounded absolutely clean and foolproof. We had crafted these rules and evolved them for over 18 months now, and they were easy to follow.

Codex ended up with 180 Jira tasks. I expected it, and then I said:

"Go ahead and implement all of them, no worktrees, serially."

This was because we were dealing with a codebase with several Rust services, and I was low on disk space, so I had no choice.

Two days later (with several interruptions), Codex was done. Record speed, tbh. Building by hand would have taken a month. Close supervision with Codex would still have taken weeks.

Then I started reviewing. The first few PRs were great. Then I got to the 25th PR. Shit hit the fan.

Suddenly, raw SQL in a codebase where the rule was, "Only use ORMs unless the query cannot be expressed cleanly." Simple SELECTs as raw SQL. Folder structures that didn't align with any existing service or standard; free-standing functions in files that should contain only API entry points; devilish string manipulations.

At some point, it cloned the entire Toasty ORM codebase as an internal library so it could add custom functionality. I should mention that this happened when I gave it a specific instruction.

I was stunned.

After tons of reviews and fixes, it was cleaned up. I didn't know what went wrong, but I suspected that the long-running session across several bite-sized instructions might have been responsible. However, I had no proof.

Then, a few days ago, we needed two crucial services, one with its own frontend implementation. I changed strategy this time because the last bout of PR reviews had drained me. I just wanted to deal with fewer PRs.

So I told Codex: "Implement the entire spec and raise the PR."

Each service was spotless. It seemed like I had written the whole thing by hand, embodying the very essence of my coding philosophy.

Then it hit me, and I'll tell you what I think the problem was.

It wasn't just context rot. It was the many decisions Codex had to make. Each wrong decision in an implemented PR led to a worse decision in the next PR, and the next, and the next, such that the last PR in the chain contained unrecognisable code.

Each mistake reinforced to Codex that it was okay to do that and to break standards. Having Codex simply implement the entire spec in one go reduced the mistakes to a negligible number. Rather than referring to its own previous PRs as sources for decision-making, it seemed to rely on the existing codebase and its current context.

But you'll say, "What did your skills and AGENTS.md files say?" I wouldn't be fair if I didn't state one crucial, repeated instruction all over the agent files:

Refer to existing patterns in the codebase. Ensure conformity and do not invent patterns unless existing solutions do not cover it, and you must state your justification in comments.

So friends, sometimes hand-holding and granularity can hurt more than you think. Trust AI more, give AI greater implementation autonomy within established architectural boundaries, rather than forcing excessive task decomposition.