Onboarding Your New AI Teammate

Published ....
Last modified ....
From Boston, MA

Share this post on BlueskySee discussion on Bluesky

I initially started the draft of this post in April, it's crazy to think about how far we've come as an industry learning about and adopting AI development tools and techniques. It wasn't so long ago that most people would be up in arms about whether to use AI or not as part of the development lifecycle, and now it seems its either taken for granted in most teams, or set as a baseline expectation across many companies.

Even through all that time since I started this post, I haven't yet been able to shake the thought that we're reinventing the wheel a bit when it comes to preparing our codebases to be optimized for AI contributions.

As I understand it, the current state of the art for managing coding agents understanding of your codebase is through either (or both in many cases) a CLAUDE.md file and a AGENTS.md file, those files are often joined with various other "config-like" directories or files to add in additional skills, rules, MCP servers, documentation, or even plans.

In effect, what we've done is create net-new patterns to document our codebase, when we've already had the tools to do so for human contributors.

In place of either CLAUDE.md or AGENTS.md, we have had both README.md and CONTRIBUTING.md documents, explaining to humans what this project is, and how can they contribute to it respectively.

In place of skills or rules, we have validation usually in the form of type checking, static analysis, lint rules, etc.

In place of various plan documents, we have RFCs, ADRs, or a full blown issue tracker