# Neutron Engineering Handbook

> Our rules for building software with AI agents. On a client project, the client's stated requirements take precedence.

Start here: [Start on a project](/new-project/). Your first ticket on a project. Understand the flow, run it locally and choose your branch. New to coding with agents? Read [Develop with agents](/agent-development/) first.

## The rules

1. **Agents write the code, not people.** We build with Claude Code and Codex. Engineers scope the work, give the agent its context, check the evidence, and own the result. Don't patch code by hand: have the agent correct it, and capture recurring mistakes in tests or instructions.
2. **One ticket, one purpose.** The agent starts from the ticket's outcome and acceptance criteria, and the PR changes only what that needs. A large PR is fine if it does one thing and its evidence makes it checkable. A PR that mixes a feature, a refactor and drive-by fixes isn't. The description says why.
3. **Keep the agent's context true.** `AGENTS.md`, `CLAUDE.md` and the docs are what every agent works from, so a wrong doc is worse than a missing one. Fix an instruction in the PR that makes it wrong, and keep plans and working notes in the PR or ticket, not the repo. After every release, align the docs with the code: correct, add, restructure, and delete what nobody can place. Prefer a test or an enforced check to another paragraph.
4. **Green has to mean it works.** Show evidence that each acceptance criterion is met and that affected existing behaviour still works: tests written from the criteria, and a run of the real thing where tests can't reach. Evidence holds only for the commit it ran on: when the code changes, collect it again. Say what wasn't verified. Deleting, skipping, loosening or disabling a check needs a stated reason and the reviewer's explicit agreement.
5. **Every change has a human owner and a human approver.** The owner can explain what the change does, how it fails and how to undo it. A second person approves before merge. AI review advises; it doesn't approve.
6. **Agents work inside hard limits.** Only approved tools see our code. Never embed secrets or real personal data in source code, prompts or logs. Production and destructive actions need a person's explicit go-ahead, however the agent runs. Permissions and tooling enforce these limits; an instruction alone isn't a limit.

## Task checklist

- **I’m about to open a pull request:** PR-1, PR-2, PR-5, CI-1, REL-2, API-1, SEC-2, SEC-3
- **I’m about to review and merge a pull request:** AI-3, PR-3, PR-4, PR-6
- **I’m about to change vouchers, points or balances:** VAL-1, VAL-2, VAL-3, VAL-4, VAL-5, VAL-6, VCH-1, VCH-T1, VCH-T2, VAL-7, VAL-T3, VAL-T4, VCH-T3
- **I’m about to protect SMS and OTP sends:** OTP-1, OTP-2, OTP-3, OTP-4, OTP-5, OTP-6, OTP-T1, OTP-T2, OTP-T3, OTP-T4, OTP-T5, OTP-T6, OTP-T7
- **I’m about to issue points or vouchers in bulk:** VAL-8, VAL-3, VAL-7, VAL-T1, VAL-T2
- **I’m about to change the database schema:** MIG-1, MIG-2, MIG-5, MIG-T1, MIG-T3
- **I’m about to call an external service:** EXT-1, VAL-6, EXT-T1, EXT-T2
- **I’m about to add or change a background job:** JOB-1, JOB-2, JOB-3, EXT-1, JOB-T1, JOB-T2, JOB-T3, JOB-T4, JOB-T5
- **I’m about to launch a campaign:** VAL-7, CMP-1, CMP-2, CMP-3, CMP-4
- **I’m about to hand work to an AI agent:** AI-1, AI-2, AI-3, PR-4
- **I’m about to ship a release:** REL-1, REL-2, REL-3, REL-4, REL-8, REL-5, REL-6, REL-7, API-1
- **I’m about to change permissions or tenant-scoped data:** SEC-1, SEC-3, SEC-T1, SEC-T2
- **I’m about to handle a production incident:** INC-1, INC-2, INC-3, AI-2
- **I’m about to prepare for go-live or a major release:** SSAT-1, REL-8, REL-5, REL-6