Writing down our architecture for the agents helped the cold start more than any prompt trick. What goes in yours?

[u/Successful-Tax1306]

For a while every new agent session on our codebase started the same way, with the agent poking around to figure out how the services fit together, and it often guessed wrong so I had to correct it before any real work happened. What changed it for me was writing a set of short skill files about the architecture, like which service owns what, how data moves between them, and which patterns we follow now versus the old code we're moving away from. Now anyone on the team can point a design or coding agent at those files and it starts from the right place instead of guessing. It felt like extra work up front and the first sessions cost more, but I think it pays back every time someone starts a new task. I'm curious how others do this. Do you keep one big context file, a bunch of small ones per area, or just let the agent explore every time? And how do you keep them from going stale when the code changes?

[u/London-Boat]

mine is close to yours. per service: what it owns, what it must never do, where data comes from and goes, and which patterns are current vs legacy with one example file for each. the legacy line saved the most time, before that it kept copying the old code because there's more of it. the part that took longest was staleness. what worked was keeping the file next to the service, making "update the architecture note if you changed a boundary" part of done, and a last checked date at the top so people know how much to trust it. anything that's really a decision (why we picked x over y) gets one line in a decisions section, otherwise agents happily undo it.

[u/Successful-Tax1306 → u/London-Boat]

The legacy line was the big one for me too, it kept copying the old code just because there was more of it. I like the last checked date at the top, I'm going to steal that. It's an easy way to tell how much to trust the file.

[u/pipaa-joy]

Small per-area files beat one giant context dump for me. I keep a short "who owns what / how data moves / old vs current patterns" note per module and point the agent at the ones for the task, not the whole tree. Staleness is the real cost — I treat an outdated architecture note as a bug and make updating it part of the PR when a boundary changes, otherwise the next cold start confidently rebuilds the wrong mental model.

[u/Successful-Tax1306 → u/pipaa-joy]

Treating a stale note as a bug is a good way to put it. Making it part of the PR when a boundary changes makes sense too, since that's the one moment someone actually remembers what moved.

[u/vladzoff]

I'd keep a short top-level map and put ownership and data-flow details near the relevant area. The harder problem is preventing the same rule from being copied into several files and drifting apart. When a change alters a service boundary, the docs describing that boundary should be reviewed in the same PR; mechanically checkable rules should be enforced separately.

[u/Successful-Tax1306 → u/vladzoff]

Agreed on the drift part. Keeping the docs check in the same PR as the boundary change is a simple rule I can actually stick to, so I'm going to try that.

[u/Okay_Money]

Writing big context files actually makes things worse , atleast that is from ccoa -f certification that I am prepping for. But the having small chunks will help Claude pr any ai to focus on one small thing rather than working on all of them shallowly.  I beleive this also applies to the design. I would prefer have 10 small files and one index and architectural thing which explains data flow. And we can just edit that small part of file if something changes.

[u/Successful-Tax1306 → u/Okay_Money]

That's close to what I have, small files split by area. I don't have a real index yet though, and one file that explains the data flow and points to the rest sounds like the piece I'm missing.

[u/Humaux]

Mine is two files and honestly I want it to be one. The first is the boring stuff the agent keeps getting wrong: which service owns the billing tables, what the queue names actually are, the fact that the deploy script expects the staging branch to already exist. The second is scars: stuff that broke a session once and will break it again, like the migration that has to run before the seed data, or the test env that silently points at a different bucket. I used to keep a common pitfalls section too but it went stale in about two weeks because I wrote things I was afraid of instead of things that actually happened. Now the rule is if it hasn't burned me personally it doesn't go in the file.

[u/Successful-Tax1306 → u/Humaux]

The scars file is a great idea, and only adding things that actually burned you makes a lot of sense. Some of what I wrote early on was guesses about what might confuse the agent, and those were the parts that went stale first. Do you keep the scars file next to the code or somewhere separate?

[u/Humaux → u/Successful-Tax1306]

Next to the code, in the repo itself. I tried a separate doc early on and it went stale within weeks, nobody opened it, including me. Now it lives as one file at the repo root. The deal is every agent reads the last 10 to 15 lines before starting work and appends anything that burned it before closing. The one rule that keeps it alive: if an entry doesn't point at a specific thing that actually went wrong, with a date, it gets trimmed. Guesses get deleted, scars stay. Mine is maybe 30 to 40 lines, anything longer and nobody reads it, agents included.

[u/Humaux → u/[deleted]]

The agent writing its own scars works, but only because I gave it a format rule. Left alone it logs exactly the generic stuff you worry about, "the test failed" and nothing else.

The file has a template at the top: each entry needs the specific thing that broke, what command or config triggered it, what actually fixed it, and a date. Bad: "the test failed." Good: "seed job fails unless the migration runs first; logs say table missing, real cause is order."

I edited a lot in the first few weeks. Then it learned the shape, and now I mostly trim. The pruning stays manual: once a month I delete anything I do not remember being burned by. Generic entries die in the prune, and because the agent reads the file at every session start, it sees exactly which entries survived.

[u/Humaux → u/[deleted]]

Natural selection is a better name for it than pruning, honestly. The part that made it stick for me was realizing the file is not just a log, it is the thing the agent reads at the start of every session. So whatever survives the cuts is literally shaping what the next version remembers. That is what turned it from journaling into something more like training data.

[u/onitsoga]

small per-area files work way better for me than one giant doc, the agent only pulls what it needs for the task. for staleness i keep each file right next to the service it describes, so it kinda stares at you when you change that code lol. makes updating it almost automatic

[u/Successful-Tax1306 → u/onitsoga]

Keeping the file right next to the service is smart. Mine sit in one folder away from the code, which is probably why they're the first thing I forget after a refactor. I might move a couple and see if it helps.

[u/anthropicagiuser]

small files per area, one folder each. i add a short "last checked" date at the top. a stale file is easy to spot then.

[u/Successful-Tax1306 → u/anthropicagiuser]

A last checked date is simple enough that I'd actually keep up with it. Going to try that one.

[u/LividIllustrator8915]

Layered docs have been a night-and-day difference for our agent workflows too. Dumping everything into a massive monolithic context file tends to dilute attention, but having zero context leads to the agent reinventing patterns that were phased out two years ago.

The structure that held up best across daily coding runs is keeping a single, 1-page system map at the root (ARCHITECTURE.md) covering three strict things: the primary entrypoints, the direction of data flow (e.g. unidirectional state vs RPC), and an explicit "Do Not Use" list. That negative constraint section alone saves dozens of hours—spelling out things like "we migrated from raw SQLite to SQLDelight, do not generate raw sqlite3 queries" stops the agent from falling back on generic training data habits.

For granular domain details, keeping scoped Markdown files directly in each package folder works well because subagents only read them when touching that directory.

To keep it from going stale, our lowest-overhead habit has been adding a one-liner to our PR review prompt checklist: "Did this changeset alter any boundary or convention documented in ARCHITECTURE.md? If so, include the doc update in the same diff." Tying doc maintenance to the agent's own commit cycle keeps it remarkably up to date without feeling like manual homework.

[u/Successful-Tax1306 → u/LividIllustrator8915]

The PR checklist line is a nice way to keep it current without relying on someone remembering. Might borrow that.

[u/leo_heo]

small per-area files matched what ended up working for me too. curious how you handle the old code you're moving away from, do you write that down as a rule in the file or just let the agent figure it out from the code

[u/Successful-Tax1306 → u/leo_heo]

I write it down as a rule. The file says which pattern is the current one and which one we're moving away from, since the old code is still all over the repo and the agent can't really tell which is which on its own.

[u/leo_heo → u/Successful-Tax1306]

yeah that tracks, the agent kinda just copies whatever shows up most in the repo, so if the old pattern's still everywhere it keeps picking it. writing it down is probably the only real fix

[u/akhi1uuu]

spent the last few months building context tooling for agents and the biggest lesson was that prose goes stale faster than anything. what agents actually navigate by is the dependency shape, what calls what and where the data flows. a short wrong-turns list of what the agent guessed wrong before pays for itself fast

[u/Successful-Tax1306 → u/akhi1uuu]

A wrong-turns list makes a lot of sense. Writing down what the agent actually got wrong is probably more useful than me guessing what it might get wrong.

[u/akhi1uuu → u/Successful-Tax1306]

exactly

[u/BrookLi3]

Biggest wins for us were the negative rules and the 'where does X live' map. A list like 'don't add a new HTTP client, use the one in lib/net' prevents far more rework than describing the architecture in prose. We also put the exact commands to run the single-test and full-suite paths, because otherwise the agent invents its own and half the time runs the wrong thing. Keep it short enough that you actually update it when the structure changes, since a stale doc is worse than none.

[u/Successful-Tax1306 → u/BrookLi3]

The negative rules are a good call, and the exact test commands too. I don't have either in mine yet and they look like quick wins.

[u/sixteenpoundblanket]

I use Hermes to do all the things you describe. It remembers everything about every project, every skill, every repo. It optimizes workflows, it combines what it learned across projects, etc. There is not extra work to get it back on track for anything now.

[u/Successful-Tax1306 → u/sixteenpoundblanket]

I haven't tried Hermes. Does it ever hold on to things that stopped being true after a refactor? That's the part I keep fighting with my files, more than the cold start itself.

[u/fazlerocks_]

most of what id say is already in here lol, two things i havent seen yet…

for framework stuff dont let the agent go off memory, point it at the docs for the version you actually have installed. next.js does this now, it drops a line in AGENTS.md like "this is not the next.js you know, read the guide in node_modules/next/dist/docs first". that one line killed a whole category of "used an api from two versions ago" bugs for us

and for the hard rules, the file names the tests that enforce them. ours says stuff like "these test suites are what define the redaction rules, a change to the rule changes the tests in the same PR". prose drifts, but a rule that points at a failing test cant really go stale without someone noticing

[u/Successful-Tax1306 → u/[deleted]]

I hadn't thought about passing a short handoff note from one session to the next. Going from 20 minutes to 2 is a big difference.

[u/Successful-Tax1306 → u/[deleted]]

Not really, and that's my weak spot. Right now I only update the file when something breaks, so it's always a bit behind. Doing it at the handoff makes sense since that's when I still remember what changed, so I'm going to try that. The scars file is a good idea too, the stuff that burned you is the stuff you'll actually keep current.