{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreid3jfwx3k5nugfulgqxivxcr34ij3zik56ybksmssqrat3s5u5ooe",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3moxju6rs3tg2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiemmemzyuryppasvsc627wwlhi46dt45ntsaaonlqjgtio564j2ty"
    },
    "mimeType": "image/webp",
    "size": 77238
  },
  "path": "/mickyarun/we-keep-our-architecture-rules-in-the-repo-the-ai-and-the-new-hire-read-the-same-file-48me",
  "publishedAt": "2026-06-23T13:23:04.000Z",
  "site": "https://dev.to",
  "tags": [
    "ai",
    "nestjs",
    "devops",
    "productivity",
    "Bodhiorchard"
  ],
  "textContent": "A few weeks ago I watched an agent build a feature beautifully.\n\nClean code. Tests passed. Did exactly what I asked.\n\nThree sessions later, I opened the same service and didn't recognise it. Nothing was _wrong_ , exactly. Every individual decision was reasonable. Stacked together, they'd quietly walked the codebase somewhere I would never have designed it.\n\nThat's when it clicked. The problem wasn't the model. The model was great. The problem was that every session started from zero — no memory of the boundaries I'd been protecting, no idea which patterns were load-bearing, no clue about the trade-off I made three weeks ago for a reason I never wrote down.\n\nI'd seen this exact failure before. Just with humans.\n\n##  The new hire who never read the docs\n\nYou know the version. Someone joins. They're sharp. They ship something in week one that works — and breaks an unwritten rule nobody told them about. Not their fault. The rule lived in my head, or in a Slack thread from last March, or in the muscle memory of whoever's been here longest.\n\nSo we'd explain it. Then explain it again to the next person. The \"why\" never made it anywhere durable. It just got re-explained, badly, on demand.\n\nAn AI session is a new hire who shows up brilliant, fast, and with total amnesia. Every single time. Re-explaining the codebase to a fresh chat window every morning is exhausting, and honestly I'd forget half of it under pressure anyway.\n\nSame problem. I'd just been solving it twice.\n\n##  One source of truth, two audiences\n\nHere's the shift that fixed it for us: the context an AI agent needs to not wreck your codebase is _the same context_ a new engineer needs on day one.\n\nNot similar. The same.\n\nWhich patterns are deliberate. Where the boundaries are and why crossing them costs you. What \"done\" means here. Which decisions are settled and which are still up for debate. A human needs that to contribute without breaking things. An agent needs that to contribute without breaking things.\n\nSo we stopped keeping it in our heads and started keeping it in the repo. Plain markdown. Committed. Versioned with the code it describes.\n\n\n\n    service-payments/\n    ├── CLAUDE.md          # how this service works, and why\n    ├── src/\n    ├── test/\n    └── ...\n\n\nA root `CLAUDE.md` (or `AGENTS.md` — pick the convention your tools read) carries the project-wide principles. Each service that has real rules of its own gets its own. When an agent opens that service, it loads the file automatically. When a human opens that service, the same file is sitting right there, written so a person can actually read it.\n\nOne file. Two readers. Nothing to keep in sync, because there's only one of it.\n\n##  What actually goes in the file\n\nThis is where most teams get it wrong. They dump the obvious in there — \"we use TypeScript,\" \"run the tests before you push\" — and the file becomes noise everyone scrolls past.\n\nThe rule I use: **a line earns its place only if leaving it out would let a plausible, reasonable-looking mistake sail through review.**\n\nThat filter kills most of what you'd be tempted to write. What survives is the good stuff:\n\n\n\n    ## Boundaries\n    - Services talk over the message bus, never direct HTTP to each other.\n      If you need another service's data synchronously, that's a design\n      smell — raise it, don't route around it.\n\n    ## Validation\n    - Every inbound payload is parsed by a schema at the edge. No raw\n      request bodies past the controller. A missing field fails loud on\n      the way in, not three layers deep at runtime.\n\n    ## What \"done\" means here\n    - A feature isn't done when it works. It's done when the next person\n      can tell what it does without asking you.\n\n    ## Settled vs open\n    - SETTLED: how we do idempotency. Don't reinvent it; copy the pattern.\n    - OPEN: our caching story. If you touch it, expect a conversation.\n\n\nNotice none of those are syntax. They're _judgment_. The settled-vs-open split alone has saved me hours, because it tells both the agent and the human where to copy an existing pattern versus where to stop and ask a person.\n\nThe \"why\" matters as much as the rule. \"Don't call services directly\" is an order. \"Don't call services directly, because the moment you do you've created a hidden dependency that nobody can see until it breaks at 2am\" is something a human will actually remember and an agent will actually respect.\n\n##  The honest part\n\nThis isn't free, and it isn't a silver bullet.\n\nThe files rot if you let them. A rule that's no longer true is worse than no rule — it teaches the wrong thing to two audiences at once. So they get reviewed like code, because they _are_ code now. When a settled decision changes, the file changes in the same PR. If that feels like overhead, it's the overhead you were already paying in repeated explanations — just made visible.\n\nAnd no, I didn't stop using AI tools while waiting for the perfect setup. The point isn't to control the agent. It's to make sure my long-term thinking is still present in a codebase that's increasingly being written by someone — something — that wasn't in the room when the decisions got made.\n\n##  When one file stops being enough\n\nA markdown file works until it doesn't. One service, a handful of rules — `CLAUDE.md` is perfect. But spread it across a dozen services and the _tending_ becomes the whole job. The rules drift from the code they describe. The \"why\" behind a feature ends up split across a spec, a ticket, a PR description, and a conversation nobody can find six weeks later. The flat file can't keep up, and a stale rule teaches the wrong thing to both readers at once.\n\nThat rot is what pushed me to build Bodhiorchard — an open-source, self-hosted project I've been working on independently (Apache 2.0, runs on Claude Code). Same idea as the file, taken further. Instead of one feature's knowledge scattered across tickets, everything for that feature lives in a single living document: the spec, the tech spec, the test plan, the acceptance criteria, the full history — tied to the actual code. And the knowledge layer stays current by syncing from the code and those docs automatically, so it's semantically searchable by a human and fed straight into every agent's prompt.\n\nThat's the part I care about most. Not a wiki you have to remember to update. A wiki that's current _because_ it's wired into where the work already happens. Confluence goes stale the day you write it. This doesn't, because nobody's job is to keep it alive by hand.\n\nThe principle never changed. One source of truth, two audiences. I just got tired of being the sync engine.\n\n##  What changed\n\nLess re-explaining. That's the boring, real win.\n\nNew engineers read the same file the agent reads, and it turns out the document you write for a machine that takes everything literally is a _really_ good onboarding doc. No assumed context. No \"you'll pick it up.\" Just the actual shape of the thing.\n\nAnd the drift slowed down. Not because the agent got smarter — because it finally knew which walls were load-bearing.\n\nI used to think the codebase lived in the code. It doesn't. Half of it lives in the decisions _around_ the code — and for years I kept that half in my head, where exactly one reader could access it.\n\nNow it's in the repo. Where everyone can. Human or not.\n\nIf you're letting AI write a meaningful share of your code: where do the rules of your codebase actually live right now? And who can read them?",
  "title": "We Keep Our Architecture Rules in the Repo. The AI and the New Hire Read the Same File."
}