AI-Assisted Coding: Best Practices & Pitfalls

AI coding tools are, at this point, table stakes. The question is no longer "should we use them" but "how do we use them without losing control of our codebase." That distinction matters because the failure modes of aggressive AI adoption are subtle: code that looks clean but is poorly understood, productivity gains that turn out to be velocity borrowed against future maintenance debt, security incidents caused by models that confidently do the wrong thing with credentials or user data.

This article is a practical guide for engineers who are past the novelty phase — you have seen what AI coding tools can do, you want to use them seriously, and you want to do it in a way that makes you and your team better rather than dependent. We cover the non-negotiable practices that professionals follow, the pitfalls that are most commonly underestimated, and how to build team-wide norms that capture the benefits without the hidden costs.

Always Review Every Diff

This is the foundational rule from which everything else follows. When you commit AI-generated code without reading it, you are not just gambling on that specific diff — you are eroding the mental model you need to debug the system when something goes wrong at 2 AM. You are also signalling to yourself and your team that authorship and understanding are separable, which they are not.

Reviewing AI-generated code is different from reviewing a colleague's PR. A human collaborator brings context, judgment, and an understanding of your codebase. A model brings none of those things; it brings pattern matching over its training data. That means the failure modes are different too:

• Confident incorrectness — the model produces code that is syntactically correct, stylistically clean, and logically wrong. No compilation error will catch this.
• Constraint violation — you said "don't change the public interface" and the model changed it anyway, subtly, in a way that only breaks downstream callers you aren't running locally.
• Scope creep — the model "helpfully" refactored a function you didn't ask it to touch, and introduced a regression in the process.
• Hallucinated APIs — the model called a function that doesn't exist in your version of the library, or used a flag with inverted semantics.

None of these failures are caught by "it looks plausible." They require reading the code with the question "is this actually correct?" not "does this roughly match what I asked for?"

A practical review checklist for AI diffs

• Does it do what I asked, and only what I asked? (Check for unrequested changes.)
• Are there any APIs, functions, or library features I don't recognise? (Verify they exist and have the semantics assumed.)
• Are there any error paths that silently swallow errors or return wrong status codes?
• Does the code handle the edge cases I care about — empty input, zero values, concurrent access?
• Is any sensitive data (credentials, PII, internal endpoints) exposed in logging or error messages?
• Does the code match the team's conventions — naming, error wrapping, log format?

Maintain Your Understanding of the Code

The productivity trap of AI coding is that it is easy to ship code you don't fully understand. The first time you merge a non-trivial function without understanding it, you've accepted a liability: when that function breaks — and it will — you'll spend debugging time building the understanding you should have had at merge time, but now under pressure, in production, with customers affected.

The "understand before merging" rule is not just about incident response. It is about maintainability over time. Code that no one on the team fully understands tends to be worked around rather than evolved — developers add hacks rather than modify code they can't reason about, and the architecture degrades faster than it otherwise would.

Techniques for maintaining understanding

• Use the AI to explain its own output. After generating code, ask: "Explain how this works, including any non-obvious choices." If the explanation reveals something you didn't expect, investigate before merging.
• Write the commit message yourself, in detail. The discipline of writing "this changes X to Y because Z" forces you to articulate your understanding. If you can't write a precise commit message, you don't understand the change well enough.
• Pair the AI output with tests you wrote. Writing the tests yourself — even if the AI wrote the implementation — requires understanding what the correct behavior is.
• Can you defend this in a PR review? Imagine a skeptical senior engineer asking "why does this take a pointer instead of a value?" If you can't answer that for every non-trivial choice in the diff, find out before merging.

There is an important calibration here: "understand" does not mean "could rewrite from scratch." It means "can explain what it does, why the major design choices were made, and what would need to change if the requirements changed." That bar is achievable for every function you merge.

Use AI to Write Tests and Self-Verify

One of the most powerful workflows in AI-assisted development is closing the loop automatically: generate code, generate tests, run tests, iterate. This is especially effective with agentic tools that can execute commands, because the model can catch its own mistakes without you doing anything.

The self-verify workflow

1. Describe the function or feature you want, including the acceptance criteria as concrete testable behaviors.
2. Ask the model to write the tests first (or write them yourself if the spec is complex enough that you don't trust the model to derive them correctly).
3. Ask the model to implement the code until the tests pass, running go test / pytest / jest after each iteration.
4. Read the final implementation and tests together — the tests document the expected behavior and make the implementation easier to understand.

# Prompt to an agentic tool (e.g. Claude Code)
Implement a sliding-window rate limiter in ratelimit/ratelimit.go.

Spec:
- func NewLimiter(limit int, window time.Duration) *Limiter
- func (l *Limiter) Allow(key string) bool
- Thread-safe; use sync.Mutex
- Pure in-memory; no external dependencies

First, write the table-driven tests in ratelimit/ratelimit_test.go
covering: under limit, at limit, over limit, window reset, concurrent
access (use t.Parallel + race detector).

Then implement until `go test -race ./ratelimit/...` passes.
Show me the test output before and after.

A critical nuance: when you ask the model to write tests for code it also wrote, there is a risk the tests encode the model's assumptions rather than the correct specification. For anything where the spec is ambiguous or the stakes are high, write the tests yourself — or at minimum review them as carefully as the implementation. Tests are specifications; let the model write boilerplate but own the behavior assertions yourself.

Keep Iterations Small

The temptation with AI coding tools is to describe a large feature in one prompt and let it generate everything. This rarely works well: the output is harder to review, harder to understand, harder to revert, and often less correct than smaller focused generations. The model's attention degrades over long, complex tasks; constraint satisfaction gets worse as the number of constraints grows.

Small iterations also force a tighter feedback loop. If you generate one function, run the tests, and they fail, you know exactly which function to look at. If you generate a hundred lines across five files and the tests fail, you have a much harder debugging problem.

What "small" means in practice

• One function or one file per generation for non-trivial logic.
• One conceptual change at a time — change the data model, then update the business logic, then update the API layer. Not all three at once.
• Commit after each verified step. Frequent commits mean short blast radii: if a later step goes wrong, you revert to a known-good state rather than losing everything.
• Test at each step. Don't accumulate un-run code. Run tests after every generation, even if the tests don't fully cover the new code yet.

This discipline feels slower in the moment but is faster end-to-end. A ten-step iteration with five-minute steps and tests at each step is thirty minutes of time you feel confident about. A one-shot generation of the same scope that takes thirty minutes to review and an hour to debug when it goes wrong is slower, not faster.

Deliberate Context Management

Every AI coding session exists within a context window. What is in that window determines what the model knows about your codebase, your conventions, and your constraints. Leaving context management to chance — letting the tool auto-decide what to include, or never providing relevant files — is a major source of output quality variance.

What to manage explicitly

• Relevant existing code — always include the function you're changing, its immediate callers and callees, and the data types it operates on.
• Conventions the model can't infer — if your team has non-standard error handling, logging format, or naming conventions, explicitly state them or paste an example. The model will default to the most common pattern in its training data, which may not be yours.
• Prior decisions in the session — in long agentic sessions, periodically summarise what has been decided and paste it back in. Models lose track of early decisions as the conversation grows.
• What has already been implemented — when implementing multi-step work, start each step by pasting the output of the previous step as context, not just the original spec.

Context hygiene for agentic tools

For tools like Claude Code that maintain a long-running session, context compaction (summarising old turns) is automatic but lossy. Important constraints stated early in a long session may be forgotten or underweighted by the time the model is working on step 7. The defensive habit is to restate critical constraints at the beginning of each major step, not just once at the start of the session.

# Start of each major step — restate the invariants
Step 3 of 5: implement the payment reconciliation job.

Invariants (apply to all code in this session):
- Go 1.22, no new dependencies beyond what's in go.mod
- All DB writes must be in explicit transactions; never autocommit
- Log at key decision points with key=value format using slog.Default()
- Do not touch files outside the /jobs/ directory

Current state: Steps 1-2 are done. The job is registered in scheduler.go
and the DB schema migration (jobs/migrations/20260512_reconcile.sql)
is applied. Now implement jobs/reconcile.go with the reconcile logic...

When Not to Use AI Coding Tools

AI tools are powerful defaults but not always the right choice. Recognising when to put the tool down and think for yourself is a mark of engineering maturity.

Security-critical code

Cryptography implementations, authentication logic, and authorisation checks should be written with extreme caution. Not because models are especially bad at these — they often produce correct-looking code — but because the consequences of subtle errors are severe and the errors are subtle. A model might generate a timing-safe comparison for passwords but miss that you're also exposing a secondary oracle through a different code path. For security-critical code, prefer well-audited libraries, read the implementation source, and consider a dedicated security review regardless of how the code was written.

Novel or poorly-documented domains

Models are trained on existing code. If you're writing code for a new protocol, an internal proprietary system, or an API that changed significantly after the model's knowledge cutoff, the model will extrapolate from what it knows and may be confidently wrong about specifics. In these cases, always verify against the primary documentation, not just the model's output.

Architecture decisions

AI tools are good at implementing within an architecture, not at choosing the architecture. Asking a model "should we use a message queue or direct HTTP calls for this integration?" will get you a plausible answer, but that answer is based on generic patterns, not your specific constraints — team size, failure tolerance, operational budget, existing infrastructure. Use the model to explore tradeoffs if useful, but own the decision yourself.

When you need to deeply understand something new

If you're learning a new language, framework, or concept, letting AI write all the code for you is counterproductive. The struggle of writing code manually, making mistakes, and debugging them is how understanding forms. Using AI as a supplement (explaining concepts, checking your work) is valuable; using it as a replacement (generating all the code) leaves you with a working program and a shallow understanding.

Secrets, Privacy, Licensing, and Compliance

These are the areas where AI coding tools create real organizational risk, and where many teams are under-prepared.

Secrets and credentials

Never paste credentials, API keys, database passwords, or private keys into a prompt sent to any cloud-hosted model. This should be obvious but it is violated regularly in practice, often accidentally — a developer pastes a config file to ask about a setting and forgets it contains production credentials. Establish a habit: before pasting any file or code block into a prompt, scan it for anything that looks like a secret. Use environment variables in examples; sanitise real values to YOUR_API_KEY_HERE before pasting.

PII and sensitive data

Similarly, do not paste real user data — names, email addresses, payment info, health data — as examples or in error messages you're debugging. Use anonymised or synthetic data. For many organisations this is not just good practice; it is a legal requirement under GDPR, HIPAA, or similar frameworks. Check your organisation's AI tool policy for specific requirements about what data can be shared with which services.

AI-generated code and security vulnerabilities

Models can introduce security vulnerabilities that a human reviewer might not immediately recognise as such. The most common categories in AI-generated code:

Licensing and IP

AI models are trained on vast amounts of open-source code. For most organisations and most output, this is not a practical concern — the model is generating boilerplate patterns, not reproducing specific copyrighted implementations. However, for production code in commercial contexts, it is worth knowing your organisation's policy. Some enterprises have approved only specific AI tools for specific use cases; others have blanket restrictions. Consult your legal or policy team if uncertain.

AI-Introduced Technical Debt and the "Looks Right" Trap

One of the most insidious failure modes of AI coding is technical debt that looks like clean code. Human-written technical debt is usually recognisable — a TODO comment, a naming inconsistency, an obvious hack. AI-generated technical debt is often stylistically clean, well-formatted, and structurally consistent with surrounding code. It just makes poor design choices that only become visible later.

Common forms of AI technical debt

• Unnecessary abstraction. Models tend toward general solutions. Asked to add one endpoint, they may create an entire framework for "configurable endpoints." This abstractions-for-no-reason pattern adds indirection without benefits.
• Inconsistent error handling strategy. A model generates code with different error-handling conventions across different functions — some log-and-return, some panic, some return a wrapped error — because it is generating each function somewhat independently.
• Missing domain invariants. The model implements the happy path correctly but doesn't know your business rules. An invoice total that must always equal the sum of line items won't be enforced unless you specify it explicitly.
• Optimistic concurrency. Generated code often doesn't think about concurrent access unless you ask. Race conditions in AI-generated code are especially hard to spot in review because the code looks structurally sound.
• Bloated dependency footprint. A model asked to "parse a URL" might reach for a full URL parsing library when url.Parse from the standard library suffices. Review every new import.

The "looks right" trap is compounded by the fact that these issues often pass code review. Reviewers are pattern-matching against "does this code look like it does what it's supposed to?" rather than "is this the right design?" Explicit design review — separate from correctness review — is valuable for any non-trivial AI-generated change.

Team Collaboration and Norms

AI coding is most valuable — and safest — when a team adopts consistent norms rather than leaving individual usage ad hoc. Teams without norms end up with a codebase where some code was carefully reviewed and some was merged on autopilot, with no way to tell the difference.

Norms worth establishing

• Review standard. AI-generated code is held to the same review bar as human-written code, without exception. Reviewers are not more lenient because "the AI wrote it."
• Attribution. Some teams add a convention like a commit tag or comment noting that a section was AI-assisted, so reviewers can apply appropriate scrutiny. Others prefer not to distinguish at all. Either is fine; pick one consistently.
• Shared prompt library. For common tasks (writing migration scripts, scaffolding new service handlers, generating test fixtures), maintain a shared library of high-quality prompts. This raises the floor across the team and prevents everyone from independently learning the same lessons about which prompts work.
• Domain-specific guardrails. Identify the areas of the codebase where AI assistance requires extra review — security-critical code, payment logic, infrastructure config — and explicitly call this out in contribution guidelines or PR templates.
• CI enforcement. Run linters, static analysis, and security scanners in CI for all code regardless of origin. Tools like Semgrep, Snyk, or go vet catch categories of mistakes that human review can miss, and they are especially valuable as a backstop for AI output.

## AI-assisted code checklist (if applicable)
- [ ] I have read and understood every line in this diff
- [ ] No secrets or PII were included in prompts
- [ ] All new dependencies verified against official registry
- [ ] Error handling reviewed — no silently swallowed errors
- [ ] Log statements reviewed — no sensitive data in output
- [ ] Acceptance criteria tested, not just "it runs"

Measuring Productivity Honestly

Organisations often measure AI coding productivity by lines of code shipped per day, or by how much faster developers complete tickets. Both metrics are easily gamed by AI tools in ways that do not represent real productivity gains.

An engineer who uses AI to write twice as many lines per day but reviews none of them carefully is not twice as productive — they are accumulating future debugging sessions, incidents, and refactors at double the rate. The real productivity question is not "how fast did we ship" but "how fast did we ship correct code that we can maintain."

Better metrics

A realistic expectation for teams adopting AI coding tools with good discipline: a genuine 20–40% improvement in end-to-end cycle time on well-specified tasks, concentrated in boilerplate, test generation, and documentation. This is meaningful. The teams that claim 5x gains are generally either measuring the wrong thing or have not yet paid the technical debt bill.

Developer satisfaction and skill growth

One often-ignored dimension is developer experience over time. AI tools that are used well tend to increase satisfaction — tedious boilerplate disappears, developers spend more time on interesting problems. AI tools that are used poorly — where developers feel they're just reviewing code they don't understand — tend to increase anxiety and reduce engagement. Track this. Periodic team retrospectives on AI tool usage are valuable not just for process reasons but because they surface whether the tools are actually helping or just adding a layer of opacity.

Building Long-Term Competence, Not Dependency

The most important long-term concern about AI coding is the risk of skill atrophy. If you use AI for everything for two years, what happens to your ability to write code without it? What happens to your ability to debug complex systems where the AI's pattern matching fails and you need genuine understanding?

The answer is not to use AI tools less, but to use them deliberately. Some specific habits that preserve and develop skill:

• Write the first draft yourself for at least some tasks each week. Use AI to review and improve what you wrote, rather than always generating first and editing. The direction matters for skill development.
• Debug manually before asking AI. When something breaks, spend at least 10–15 minutes with the debugger, log statements, and your own reasoning before handing off to the model. This is how debugging intuition builds.
• Read the generated code, always. Even if you don't change it, reading it carefully is how you learn from it. The model often uses library features or patterns you weren't aware of; those are worth knowing.
• Understand the tests. Tests are the most important documentation in a codebase. If AI generates them, read every assertion and understand what it is testing and why.

The engineers who will be most valuable in a world with powerful AI coding tools are not those who can prompt most fluently — those skills will commoditise. They are the engineers who deeply understand the systems they're building, can debug anything that goes wrong, and can make sound architectural decisions. AI tools are a force multiplier for those engineers. They are a liability generator for engineers who have outsourced their understanding.