A new contributor joins. They clone the repo, open their assistant, and ask it to explain the codebase. The assistant reads the code and gives a confident summary. It is mostly right. It misses the reason the queue retries only twice, the module nobody should touch before the migration, and the test that is skipped on purpose.
Code tells you what the project does. It rarely tells you why, what was tried and dropped, or which rules the team follows. That knowledge usually lives in the heads of one or two people, and onboarding becomes a week of "quick questions".
This guide shows how to package that knowledge as a few files, so a contributor and their assistant can get to a first real change in an afternoon. Everything here works with plain files in any repository.
What a new contributor needs on day one
Before writing anything, decide what "onboarded" means. For most projects, a contributor is ready when they can answer four questions:
- Map: Where do things live, and which parts matter for my first task?
- Rules: How do we build, test, name things and open changes?
- Reasons: Why is it built this way, and what did we already reject?
- Current state: What is in progress, fragile or about to change?
The first two are the usual README and contributing guide. The last two are the gap. They are also exactly what an assistant cannot infer from code, which is why a fresh session will happily propose the design you dropped last month.
An example afternoon plan
Here is one way to structure the first afternoon. Treat the times as an example, not a rule.
| Block | Contributor does | Context they use |
|---|---|---|
| First hour | Clone, set up, run tests | README, .env.example, setup notes |
| Second hour | Read the rules and the reasons | CLAUDE.md / AGENTS.md, decision records |
| Third hour | Replay one real piece of work | One or two saved sessions |
| Rest of the day | Make a small, real change with their assistant | All of the above, plus the current-state note |
The point is order. Setup first, so nothing blocks them. Reasons before code changes, so their first suggestion does not reopen a closed question.
Write instructions for two readers
Your project instructions now have two readers: the person and their assistant. Claude Code reads CLAUDE.md files. Many other coding agents read AGENTS.md. Write them so both readers get the same rules.
A short example that works for a new contributor:
# Project instructions
## Commands
- Install: `npm install`
- Test: `npm test` (must pass before any change is proposed)
- Lint: `npm run lint`
## Rules
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access only through `src/db/`. No queries in route handlers.
- Keep changes small: one concern per pull request.
## Before you change anything
- Read `.prjcontext/memory/current-state.md` for work in progress.
- Check `.prjcontext/memory/decisions/` before proposing a new library
or a structural change. Many options were already considered.
## Do not touch
- `src/legacy/export/`: frozen until the migration ships.
Keep it short and specific. Long files get skimmed by people and diluted for assistants. Put detail in separate files and point to them. The guide on writing CLAUDE.md and AGENTS.md covers this in depth.
If your team uses more than one assistant, keep one file as the source and make the other a short pointer to it, so the rules do not drift apart.
Give them the reasons, not just the rules
Rules without reasons get broken, politely, by smart people. "Why do we retry only twice?" is a fair question. If the answer is written down, the contributor finds it in a minute. If not, they either ask and wait, or change it.
The fix is a small set of decision records. One short file per decision:
# 2026-06-10 Retry failed jobs at most twice
Status: accepted
Context: Payment provider rate-limits after repeated failures.
Three retries caused account lockouts in testing.
Decision: Retry twice with backoff, then send to the dead-letter queue.
Consequences: Some jobs need manual replay. The replay script is in
`scripts/replay.ts`.
Five to ten records like this cover most of the "why" questions a newcomer will have. The article on lightweight decision records shows how to start and keep them current.
Add one more file: a current-state note. What is in progress, what is fragile, who owns what. Update it when things change, not only when someone joins.
# Current state
- In progress: moving exports to the new storage layer (Priya).
- Fragile: `src/legacy/export/`. Frozen until the migration ships.
- Good first tasks: the open issues labelled "small", or the flaky
date test in `tests/reports/`.
A list of good first tasks is worth adding here. It saves the newcomer from picking something that touches three frozen modules.
Hand over sessions that show how work is done
Documentation shows the result. A good AI coding session shows the path: how the team breaks down a task, which checks they run, how they react when the assistant goes wrong.
Pick one or two sessions that are good examples:
- A feature from plan to merged change, with the plan agreed before any code.
- A debugging session where the cause was not obvious.
Trim them before sharing. Remove long tool output, repeated file dumps, and anything personal. Then save them in the project, for example under .prjcontext/sessions/, with a one-line summary at the top.
A newcomer can read these, or ask their own assistant to summarise the working pattern from them. For choosing which sessions to keep, see which AI coding sessions are worth keeping.
Check what you share before you share it
Onboarding means giving someone new access, so this is the moment to check what the context contains.
- No real secrets in examples.
.env.examplehas names and fake values only. - Search saved sessions for tokens, keys, passwords and internal URLs that should not leave the team.
- Remove personal notes that were never meant for others.
- Give the right access level. Someone doing their first task may only need to read and clone, not push.
The guide on sharing AI coding context with your team has a fuller checklist.
How PrjLab handles this
We built PrjLab so the project and its context can be handed over together. Instructions go in .prjcontext/instructions/ (or stay as CLAUDE.md and AGENTS.md at the root), decisions and notes in .prjcontext/memory/, and the sessions you chose to keep in .prjcontext/sessions/. You push with prj push, then share the repository by handle: a reader can view and clone, a writer can also push, and removing someone takes effect immediately. The newcomer runs prj clone and gets code, instructions, memory and sessions in one folder. Every push is an immutable version with a list of changes and a line diff, so they can see how the context evolved. Repositories are private by default, and the CLI skips obvious secrets, but you still review prj status and the sessions before sharing. The getting-started guide shows the steps.
Frequently asked questions
Is this a replacement for a README or contributing guide? No. Keep those for setup and process. The instructions file, decision records and sessions add the reasons and current state that those documents usually leave out.
How many decision records do I need before onboarding someone? Start with the questions newcomers actually ask. Write a record for each one the next time it comes up. A handful covers most projects.
Should the new contributor add to the context too? Yes. Ask them to fix anything that confused them and to write a record for any decision they make. A fresh reader finds the gaps fastest.
What if my team uses different assistants? Keep one instructions file as the source of truth and point the other to it. The memory and session files are plain Markdown, so any assistant can read them.
To set up a shared project with its context, start with the getting-started guide.
