Your first project with coding agents: the complete system

TLDR: The first project with agents almost always fails for the same reason: delegating too much too soon without preparing the ground. The system that works: an instructions file that teaches the agent your project, a trust ladder starting with small tasks, everything in branches with review, and CodeRabbit as the second net catching the mechanical. With Claude Code or the free route of Gemini CLI, the system is the same.

This guide is for developers who already chose their agent (if not, choosing a coding agent is the previous step) and want to bring it into a real project without the first week ending in mutual distrust.

The idea that orders everything: the agent is a new teammate with plenty of capability and zero context. Everything you would do with that hire (document, start with bounded tasks, review their work) applies exactly.

1. Prepare the repository for the agent

The best-invested half hour of the whole process: the instructions file at the repository root. Agents read it on start, and its content is what separates a guessing agent from a knowing one: the project’s conventions (style, structure, patterns used and avoided), the commands (how tests run, the linter, local startup) and the minimum map (what lives where and which zones are off limits).

Write it the way you would write a new teammate’s onboarding document: concrete, with examples, no philosophy. And treat it as code: when the agent fails through not knowing something, the correction goes into the file, not just the conversation.

Complete the preparation with basic hygiene: passing tests (they are the verification of the agent’s work) and a tidy repository, because the agent inherits chaos just as the new human would.

2. Calibrate what to delegate with a trust ladder

Week one is not for delegating the core refactor: it is for climbing a ladder. First rung, small verifiable tasks: the specific bug, the missing test, the function with clear criteria. Second, medium tasks with a plan first: you ask for the plan, correct it, and only then it executes. Third, once results support it, long tasks with supervision at the key points.

With Claude Code, the judgment on ambiguous tasks lets you climb faster. With the free route of Gemini CLI, the same system works one rung lower: more bounded tasks, more verification. The system is identical, the cruising altitude changes.

The rung discipline: if a task comes back wrong twice, it was not that rung’s task. Lower it, slice it or do it yourself, and note in the instructions file what the agent did not know.

3. Work in branches and review every change

The system’s non-negotiable rule: the agent works in branches and you merge after reviewing. Git is the safety net that turns any disaster into a discarded branch, and review is the work remaining on the human side, with a warning collective experience has already distilled: the temptation to approve without reading grows with each agent success, and the day you approve without reading is the day of the scare.

Effective review of agent code has its technique: first the full diff at a glance (did it touch what you expected and nothing else?), then the tests (do they exist, pass, test what matters?) and finally the fine reading of the new logic. The order matters because the first filter quickly discards the big deviations.

4. Add the second net with automatic review

Your review is the main net and should not be the only one. CodeRabbit reviews every pull request on arrival: it summarizes the change, catches probable bugs and comments line by line, so your human review starts with the mechanical already filtered. Free for open source and from about $24 per developer for private repos.

The agent-plus-automatic-reviewer combination is the fastest-growing pattern for a simple reason: the volume of generated code demands an automatic first pass before human attention. The full detail is in the reviewing AI code guide.

With the system running, the next improvements are flow: parallel work is in the parallel agents guide, and the persistent context layer in product memory with PaellaDoc. The whole sector lives in AI for software development.

Common mistakes

Delegating the big task on day one. It is the recipe for disenchantment: without context or calibration, the result drifts and the wrong conclusion is “this does not work”.

Skipping the instructions file. The agent without context guesses, and guessing conventions produces that correct code that fits nowhere.

Approving without reading. The agent’s accumulated success is exactly what erodes review discipline, and the cost arrives all at once, not spread out.

Correcting in the conversation and not in the file. What was only said in chat is forgotten next session. What lives in the instructions file is permanent.

Frequently asked questions

How long until productivity shows?

With this guide’s system, week one already leaves tasks done that you did not do. The big jump lands in months one to two, when calibration is done and the instructions file mature.

Does the same system work on the free route?

Yes: ladder, branches and review work the same with Gemini CLI or Qwen Code. The difference is cruising altitude (more bounded tasks) and more verification on the ambiguous.

What exactly goes in the instructions file?

Conventions with examples, project commands and the map of what lives where. The quality test: if a new teammate could start working from that document alone, it is well written.

Can the agent break something serious?

With the branch-and-review system, the damage radius is a discarded branch. The real scares come from skipping the system: working on the main branch or merging unread.