Learn and improve
Onboard the Agent Like a New Hire
Write down what the AI needs to know about the team's work
Write an orientation document for the team's AI tools that records how the team works, then keep it current as a shared record.
Borrowed from software teams working with AI coding agents, as documented in GitHub's review of more than 2,500 instruction files and a University of Washington lab's write-up. Read the original source.
Changes a rule or role · An hour or more to set up · Anyone on the team can start it
Try this first
Write one page for your AI tool that lists what a new colleague would need to know in their first week. Include three things it should never do.
Use it when
Important knowledge about how the team works lives in a few people's heads, and the team's AI tools keep making the same avoidable mistakes.
Skip it when
Skip it when the team uses AI only for general tasks that need no knowledge of the team's own work, such as rewording an email.
How to introduce it
Ask the question you would ask before a new person joins the team: what would they need to know in their first week to avoid obvious mistakes? Write that down for the AI. Include how the work is organized, where things are kept, the terms the team uses, and examples of good finished work. Then write the rules in three groups: things to always do, things to ask about first, and things never to do. Start the AI on small tasks. Each time it makes a mistake that better instructions would have prevented, add a line to the document.
How to show up
Treat the document as the team's document, not as one person's technical setup. Ask the people who hold the most unwritten knowledge to review it, and credit what they add. When the AI makes a mistake, first ask what the document was missing before blaming the tool.
How long it takes
An hour or two for a first version. After that, short additions each time the AI makes a preventable mistake.
What makes it hard
The people who know the most have the least time to write it down. They also often do not notice what they know, because it has become routine for them. The document goes out of date unless someone owns it. Assign an owner and a regular date to review it.
What it looks like when it's working
The AI repeats fewer mistakes, and new team members start reading the document too. When someone leaves the team, less of what they knew leaves with them.
How long until it sticks
About a month of adding to the document after mistakes before it covers most of the everyday work.
How you know it stuck
When the AI gets something wrong, someone asks what the document is missing and adds it, without being prompted.
The idea behind it
Much of what makes a team effective is never written down. People learn it by asking colleagues or by making mistakes. AI tools cannot pick up that knowledge informally, so they need it in writing. Once the knowledge is written down for the AI, it is also available to new team members and to anyone covering for a colleague.
Where it comes from
Software teams working with AI agents. Software teams have found that AI agents do much better work when they get written context about the team's specific setup. GitHub reviewed more than 2,500 of these instruction files. The most useful ones listed the commands the agent could run, gave concrete examples, and set three kinds of limits: things to always do, things to ask about first, and things never to do. A research lab at the University of Washington used this approach on a 17-year-old codebase. The lab reported finishing a feature in two weeks that had been stuck for a year. Stripe built the same idea into a company-wide system, and its employees have shared about 2,000 packaged workflows. These results are reported by the organizations themselves. There is also a second benefit. Writing instructions for the AI requires people to write down knowledge that previously existed only in their heads. The team writes an orientation document for its AI tools, the way it would for a new colleague. The document covers how the work is set up, what good work looks like, what the AI may do on its own, what it must ask about first, and what it must never do. The AI starts on small, contained tasks before it gets larger ones.
Evidence
How to write a great agents.md: Lessons from over 2,500 repositories, GitHub Blog
Onboarding Claude Code like a new developer, Claude Blog A University of Washington lab describes giving the AI an orientation file, packaged know-how, and small starting tasks on a 17-year-old codebase. Results are self-reported.
Build your own company brain, Lenny's Newsletter Stripe's internal AI system, where employees package their own workflows for others to reuse. About 2,000 workflows are shared, according to the interview.