Frame the outcome
Describe the user need, current behavior, intended result, constraints, and what must not change.
Use AI to write software. Keep engineering in charge.
AI coding tools can compress research, implementation, testing, and iteration. The advantage comes from a better development loop, not from accepting more code with less scrutiny.
Speed matters. So does knowing what changed.
A capable coding agent can explore a repository, trace behavior, edit several files, run tests, and compare the result against a specification. That makes it more than autocomplete. It also gives it enough reach to create a convincing mistake across an entire feature.
We treat the agent as an unusually fast engineering collaborator. It can investigate and execute. It does not own product intent, architectural judgment, security boundaries, deployment authority, or the final decision to ship.
A dependable working loop.
Good results come from giving the agent something concrete to understand and something objective to verify.
Let the agent inspect
Give it room to trace the relevant code, data flow, tests, and conventions before it proposes a change.
Choose a boundary
Keep the first change small enough to understand, review, test, and reverse without guesswork.
Define proof
Name the test cases, build checks, screenshots, performance limits, or observable behavior that will count as done.
Review the diff
Check product intent, architecture, correctness, security, failure behavior, and maintainability. Passing tests are necessary, not sufficient.
Verify in the real path
Run the application, exercise representative cases, and inspect the result where users and operators will encounter it.
Give the task a real boundary.
A strong brief is short enough to use and specific enough to test. It points to the business behavior without dictating every line of implementation.
Outcome What should become true for the user or operator? Current behavior What happens now, including the failing or expensive path? Constraints What architecture, interfaces, data, security rules, and scope limits matter? Acceptance Which examples, tests, builds, screenshots, and manual checks prove the result? Delivery Inspect first. Explain the approach. Make the smallest complete change. Run the checks. Report risks and anything left unresolved.
Keep repository guidance useful.
Persistent instructions should contain the things an agent cannot safely infer from reading the code.
Include
- Architecture decisions and system boundaries
- Build, test, and validation commands
- Security rules and protected data
- Repository etiquette and release constraints
- Project-specific conventions that differ from defaults
Leave out
- Generic advice such as “write clean code”
- Documentation the agent can discover when needed
- Several versions of the same instruction
- Rules that are no longer enforced by the team
- Long examples without a measured reason to keep them
OpenAI recommends lean, nonrepetitive coding-agent prompts with explicit test expectations and acceptance criteria. Anthropic similarly recommends concise project instructions, specific context, and verification criteria. OpenAI model guidance Claude Code best practices
Review in layers.
Syntax is the shallowest layer. A serious review asks whether the change belongs in the product and the surrounding system.
Intent
Does the change solve the right user problem and preserve the behavior that matters?
Architecture
Does it fit existing boundaries, ownership, data flow, and dependencies without creating hidden coupling?
Correctness
Do representative, edge, failure, concurrency, and recovery cases behave as intended?
Security
Are inputs, permissions, secrets, dependencies, logs, and destructive operations handled deliberately?
Operations
Can the team deploy, observe, debug, roll back, and maintain it after the coding session ends?
Common ways the work goes wrong.
Most failures are not evidence that the model cannot code. They are signs that the development loop gave speed more authority than evidence.
A vague request
The agent solves a plausible problem instead of the actual one. Add the user, scenario, constraints, and acceptance criteria.
Too much at once
A large diff becomes hard to reason about and easy to approve casually. Split work by behavior or system boundary.
Instructions everywhere
Long, repeated rule files dilute the important constraints. Keep persistent guidance short, specific, and maintained.
Tests written to agree
New tests may confirm the implementation rather than the requirement. Start with representative behavior and failure cases.
Review by the same context
The agent that wrote the code is biased toward its own approach. Use a fresh review pass for consequential changes.
Authority without control
Agents can run commands and alter files quickly. Limit credentials, protect production, and keep destructive actions explicit.
Before a change ships.
Use this as a final control, not as a substitute for understanding the diff.
- The intended user behavior is explicit.
- The diff is small enough to explain.
- Unrelated code and user changes are preserved.
- Inputs, authorization, secrets, and data handling were reviewed.
- Tests cover success, edge, and failure paths.
- Static checks and the production build pass.
- The real interface or runtime was exercised.
- Logs and observability avoid sensitive content.
- Deployment and rollback are understood.
- A person accepts ownership of the result.
Use AI review, but do not outsource judgment.
A separate AI review can find issues the implementation pass missed, especially when it starts with fresh context and explicit review priorities. Automated review should complement deterministic tools and human review. GitHub’s own guidance notes that generated code and AI review can still miss defects, produce false positives, or introduce insecure suggestions.