Say we open-sourced the agentic piece of a hospital-ops platform we're building — a planner that decides which domain agents (capacity, staffing, supply, flow) to bring in for a given situation. Realistically, most people who'd ever send a PR against it aren't going to read the entire hospital-ops app first. They'll clone it, poke at the agent code specifically, and try to fix or extend something. No teammate to ask, no internal Slack, just whatever's in the repo.
That's the scenario I can't stop thinking about, because a lot of this agent's real behavior doesn't live cleanly in the code a newcomer would be looking at. Some of its rules aren't functions anymore — they got moved into editable config outside the codebase, so reading the source will straight-up mislead you into thinking a rule does nothing, when its actual logic is sitting somewhere a first-time contributor has no reason to look. There's also a naming convention underneath it that only breaks in a subset of configurations, so a "fix" can pass every test against the default setup and be silently wrong for everyone else. And one part of the pipeline has a known intermittent bug where the workaround isn't a code fix at all — it's an operational step nobody would guess from reading the logic.
None of that is really "architecture," and a diagram wouldn't save you from it. It's closer to a pile of landmines that currently only exist as tribal knowledge.
So for anyone who's actually opened up their agent/AI code to outside contributors: what did you end up writing down that a diagram and a README didn't cover? A "known gotchas" doc, inline warnings at the exact danger spots, something more like a runbook? What's the thing a first-time contributor would've hit blind without it?
Source: r/u/Impressive_Star_1527 · by /u/Impressive_Star_1527