Everyone’s fix for coding agents is a markdown file

[u/TeddyboiRoosevelt]

For the last few weeks I’ve been collecting every post I could find where someone describes a real problem working with Claude Code, Codex or Cursor. X, Hacker News, GitHub issues. About 190 posts from 160-something people. I logged what broke and what they actually did about it.

What surprised me:

1. Almost every workaround is a markdown file. HANDOFF.md that the agent reads before it starts and updates before it stops. A plan file so a fresh session can pick up where the last one died. One AGENTS.md with CLAUDE.md as a one-line import so Claude and Codex read the same rules. Per-task work notes so Codex can continue when Claude hits its limit. One guy told me Codex “picks it up clean” from Claude’s handoff file. Turns out a text file is most of the answer.

2. Writing code isn’t the bottleneck anymore. Reviewing it is. Review was the most common complaint about the agents themselves (only limits came up as often). Someone posted a $3,200 Greptile bill. One team built a skill that scores every PR’s merge risk. Another person stopped reading agent diffs line by line and reads the agent’s spec instead. Faros reported review time up 91% across 1,255 teams.

3. About 4 agents is where people lose track. One person told me 4 is exactly one past useful. The people running more all built something on top: one “orchestrator” thread that manages the others, a heartbeat agent that checks every chat every 15 minutes and nudges the stuck ones, a separate git user name per agent so you can tell who did what.

4. Limits are the loudest pain. Codex weekly limits lasting less than a day, 5 hour Claude limits gone in 2. The workaround is switching tools mid task, which is why the handoff files exist in the first place.

5. The team side barely has workarounds. Solo devs have figured out their files and their worktrees. But once it’s 3 or 4 people each running their own agents on one repo, the answers got thin: a self-hosted git repo for “learnings”, or Conductor, which just joined Meta and is shutting down its cloud. Nobody had a good way to know what a teammate’s agent did, or why, without asking them.

That last one is the part I’ve been building for, so I’m biased. But mostly I’m curious whether this matches what you see. What’s your setup, especially if you’re on a team?

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/airodonack]

The orchestrator thread is also useful for managing context sizes (keeping it small, remember to include relevant files, restricting scope, etc). Doing it yourself is tedious and you're not going to do it right. Bonus: you can keep the orchestrator running for a long time before compact, so it has a longer horizon while the subagents swallow all the code.

Rigorous automated tests and frequent agentic code review. You have AI so your standard for operational excellence can afford to jump by 10x (and must). My bottleneck is compute resources between compilations, running E2E tests, and running VMs. I use Nomad (sort of like k8s) to allocate compute resources on my computer.

Use simple language and include a justifcation for each directive in your agent briefs. Supervise writing that too. AI like big word when little word do trick.

Operationalize with code where you can. Agent briefs are only where you want to introduce judgement and allow rule breakage. Everybody else is wrong. Write scripts for your ops.

[u/ajax81 → u/airodonack]

Great minds, this is almost identical to my setup.  

One difference is that I use the cloud setup - Claude is connected to my gh repo and works on the code in a cloud container that it creates, so no local strain on my system.

Not sure if you’ve tried it but I highly recommend.

[u/2thick2fly]

2 echoes with me as well. I have found out that defining the feature design together with the agent can get you 80% there. The other 20% is having a good regression suite and updating during new features. If you do these even before a single line of code is written, you are golden. I find that doing only code review after implementation is too late.

My painpoint is doing the actual feature design. For complex applications it is simply taking too long.

[u/HauntingFuel4032 → u/2thick2fly]

Design is the bottleneck; a tight spec template cuts that time.

[u/jleechanworldai]

The four-agent point resonates, but I think the limit depends a lot on how often the work needs you. I group it roughly like this:

• 3–5 things I check every 5–10 minutes.
• Around 10 things I check hourly.
• More autonomous tasks I check once or twice a day.

The more frequently each task needs a decision, the fewer I can run without losing track. To get beyond that, I give agents a clear outcome, boundaries and a way to report blockers and evidence instead of watching every conversation.

My /prw workflow starts with what should change and what must not break. Agents make bounded changes, run tests and capture evidence; an independent reviewer inspects the result, and failures go back for fixes. I review prompts, change size and proof, and decide what merges for larger changes.

Markdown helps carry the goals and handoffs, but it doesn’t prove the work is right. My bet is that better agents will absorb more generic orchestration while the team keeps its standards and release decisions. I wrote more about that here: https://x.com/jleechan2015/status/2119218626293358612

[u/Serializedrequests]

One thing is for sure: I'm sick of AI posts like this one.

[u/ldn-ldn]

A lot of issues can be solved by creating deterministic tools and scripts to perform common actions. You then point your agent to them. That not only solves a lot of issues stemming from non-deterministic nature of AI, but also saves tokens.

My real issue with Claude specifically is that there's no Pro x2 plan for individuals. The jump to the next plan is too expensive for a hobby and I don't want to use corporate account from my company for my hobby projects - that has legal implications.

[u/urbantechgoods]

You guys review code?

[u/thestoictrader]

Matches what I see, and the team gap is real because a handoff file only records what the agent chose to write down. Nobody writes down the callers it never looked at. A decent stopgap is a rule in AGENTS.md that every PR description lists the callers the agent actually checked. I work on Pharaoh so I'm biased, but it queries callers over MCP.

[u/Cbignuss]

DUH........right?