DevKit Lab 作者為 AI 編碼智能體撰寫入職文件，令修改更一致

The first month with an AI coding agent, I did what most people do: I got better at prompting. I learned to say "be minimal", to paste error logs, to ask for plans first. It helped a little. What actually changed things was unglamorous — I wrote the onboarding doc I would give a new hire, and pointed the agent at it.

What a new hire needs, and an agent does not get

When a person joins a team, someone tells them: what this service does, which directory holds what, how to run the tests, what must never be touched, and who to ask before doing something irreversible. None of that comes from clever prompting. It comes from a document.

An agent gets none of it and is expected to infer it from the code it happens to read. So it guesses. Then you spend your review time correcting guesses instead of reviewing intent.

The five things I wrote first

1. What this is — one paragraph, no marketing.
2. How to run it — install, run, test, lint. Exact commands.
3. The scope contract — the files it may not rename, reformat, or restructure.
4. Money and data rules — integer minor units, UTC storage, idempotency keys. The rules where a wrong guess costs actual money.
5. What needs a human yes — data deletion, schema change, prod migration, sending email to real users.

Five sections, forty lines. That is a morning's work if you already know your own codebase, and a useful audit if you do not.

What changed in practice

• Diffs got smaller. The agent stopped "tidying" adjacent code, because the contract named it.
• I stopped repeating the same three corrections every session.
• Review got boring, which is the goal. Boring review means the bar is being met before I look.

What did not change

It still forgets after a long session, still occasionally invents an API, still needs a test that fails before the fix. The doc does not make the agent good. It makes the agent consistent, and consistency is what lets you build a process on top.

The mistake to avoid

Do not write it as a style guide. Nobody reads a style guide — not people, not models. Write decisions that change behaviour, and for everything else point at the linter.

And do not write it once. Every time you correct the agent, add the correction as a line. After a month the file is the most accurate description of your codebase you own.

The template I use for section 3 (the scope contract) and section 4 (money and data) is in the kit I put together — with the review command that makes the doc binding rather than decorative: AI Agent Engineering Kit. Three of the eighteen files are free to read first.