How We Organize Our Development Knowledge Base at OpsMill

When an engineer joins a new company, learning the codebase is like drinking from a firehose.

They’re trying to understand naming conventions, architecture decisions, and the reasoning behind past trade-offs.

Even if you do a fantastic job with onboarding, and have a robust development knowledge base for new hires to review and refer back to, there will always be some context they just can’t get from reading.

All the information that lives in people’s heads and Slack threads is fine if you’re working with humans—you just go and ask someone the why or how behind something. Not so fine when you’re working with agents.

If you ask an LLM to create a new feature or fix a bug, it needs the same background any experienced engineer on your team would have. All that context needs to be referenceable in your knowledge base.

Here’s a look at how we’ve organized our knowledge base at OpsMill, how we’re constantly updating it, and where we’d like to get to. But first, a little more background.

Why our development knowledge base is unique

Virtually every company has some kind of development knowledge base—but ours needs to be in really, really good shape. It’s not just because we want our agents to contribute to our codebase, but also because we’re open source.

Anyone, not just our engineers or agents, can touch the repo. That includes our solution architects, who are technical but don’t know every detail, and outside contributors who’ve never worked at OpsMill.

While some companies maintain separate docs for humans and AI, we believe they should be one and the same. What a seasoned OpsMill employee needs to work on Infrahub is the same thing that a new hire, a non-OpsMill employee, or an agent needs to know.

How we structure the knowledge base so anyone can consume it

One main folder

.agents/ has everything an agent (and humans using an agent) can run: commands, rules, and skills.

While Claude Code operates from .claude/, we’ve got a symlink that points straight at .agents/. That way, if we end up going with a different coding tool in the future with its own folder requirement (like, say, Cursor), we can just point the new link at .agents/ too.

45 agnostic AI skills

Any of these skills can be used across various projects, not just Infrahub.

Even if a skill references something Infrahub-specific, it’s not hard coded. Instead, it links to our internal docs, which are updated on a regular basis to reflect any new naming conventions or patterns for how we want to structure something in the codebase.

Two kinds of internal docs

We’ve split our docs into two categories: dynamic docs and static docs.

1. Dynamic docs change when the systems change since they describe the system as it exists right now.
   • AGENTS.md is a map of what documentation lives where. It’s only a couple of pages but it’s the first thing read at the start of a session because it explains what a project is, what it’s built on, which commands to run, and where each kind of doc lives. It also has a list of dos and don’ts. Any docs with more depth than that sit in one of the folders below (AGENTS.md just points at them). It’s tempting to let this file grow and grow but it gets loaded on every run so, really, any extra details should move into a different folder.
   • README.md, for both agents and humans, serves as an index of our docs and how to decide when to load what.
   • knowledge/ is a rundown of how Infrahub works under the hood: what happens when the system does something, which part owns what, and why it’s put together that way. We expect people to read the relevant page before they touch an area because the design intent is usually the answer to a bug.
   • guidelines/ is a recap of how we write code at OpsMill. It’s mostly a set of rules, with good examples and bad ones, sometimes with a table to check yourself against. Think of it as the stuff a reviewer would consistently repeat. Most of it isn’t Infrahub-specific, just how we write code at OpsMill, which is why we use it across projects.
   • guides/ is a step-by-step walkthrough of how to do a specific task from start to finish. Notably, each guide opens by telling you when you shouldn’t be using it.
2. Static docs record a decision the moment it was made. Think of them as point-in-time sort of records.
   • adr/, or architecture decision records, detail why we picked a particular approach or technology over alternatives (and what tradeoffs we accepted).
   • specs/ reflect what we’re building for a specific feature. These get updated during the build, then get archived once a feature ships.

How we keep the development knowledge base fresh

Our product is constantly changing. Plus, we’re making important decisions outside of our codebase too—in Slack, meetings, and pull request (PR) comments.

To keep our agents, employees, and open source contributors working from the same source of truth, even as that source of truth changes, we run a few processes.

1. We manually edit knowledge/, guidelines/, and guides/ docs.
   When a new feature ships, someone on our team goes back to the original spec, compares it against what got built, and updates our docs to match.

   Specs shift during testing and implementation, so whatever we learn along the way should get folded back into the knowledge base so that the next person or agent building something similar, or in the same domain, starts from the right assumptions.

2. We have Claude run its own retro.
   At the end of a working session, Claude looks at where it got confused or slowed down. It examines what went awry, and then updates the docs so that it (and anyone else using the knowledge base) can avoid that issue in the future.

   See the Retrospect skill we use.

3. We have a harvesting agent learn from PRs.
   Every Friday, this agent looks at all the merged and approved pull requests and reads the commentary. Things like, “Hey, this isn’t quite the way I would’ve written this,” or “Here’s a better way to optimize for xyz” get turned into a new rule.

   Here’s an example of what one of those review lessons looks like:

   

   Want to see how it’s built? Here’s our Review skill.

What we’re working on next

Our knowledge base won’t ever be “finished.” We’re still fine-tuning the harvesting agent and trying to fully close the loop by automating the doc update part that’s manual.

In the meantime, though, we’ve got a few promising signs that it’s working pretty well.

A few weeks ago, I was working on a new feature and wanted to install a new external library.

I asked Claude to start implementing it, and it wouldn’t, because in our AGENTS.md file, we’d defined specific guardrails that say to always ask first before making:

• Database schema or migration changes
• GraphQL schema modifications
• CI/CD workflow changes
• Authentication/authorization changes

I’d forgotten it was even in there but Claude caught it. Thanks to that part of the knowledge base, we won’t be adding stale libraries that could introduce bugs and security risks.

We’ve also noticed that more experienced engineers are relieved to be putting some of their hard-earned knowledge on paper, and new hires that join our team have found the knowledge base a useful tool for ramping up.

If you’re curious how it will continue to evolve—or if you have any ideas you want to share—I encourage you to join our Discord community.