Explain the task
Describe the user need, current behavior, intended result, constraints, and what must not change.
Working with AI coding tools
Use AI to investigate, implement, and test changes. Keep scope, review, and release decisions with the engineering team.
Review the assumptions behind the code.
Coding agents can trace behavior, edit files, and run tests. They can also spread a mistaken assumption across a feature.
Let the agent investigate and implement. Keep architecture, security, deployment authority, and the decision to ship with the team.
A development workflow
Specify the expected behavior and how it will be checked.
Let the agent inspect
Give it room to trace the relevant code, data flow, tests, and conventions before it proposes a change.
Define the change
Keep the first change small enough to understand, review, test, and reverse without guesswork.
Decide how to test it
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.
Try it in the application
Run the application, exercise representative cases, and inspect the result where users and operators will encounter it.
Write a brief the model can act on.
Describe the required behavior, constraints, and checks without prescribing every line of code.
Outcome What should the user be able to do? 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.
Check the requirement, design, behavior, security, and release path.
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
Watch for these problems during implementation and review.
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.