12 — AI in the Development Workflow — Reviews, Refactors, and Docs

"AI helps me code" lumped three very different touchpoints into one blob. Separating them into units of work is what made each one useful: *review is find (detect issues in existing code), refactoring is transform (restructure without changing behavior), documentation is generate (produce prose from code).* [1] Each shines when scoped to its unit and disappoints when asked to do another's job.

The frame that helped is the verb. A code review tool's job is to surface things I might have missed — that's a find operation over the diff. A refactoring tool's job is to rewrite code preserving behavior — that's a transform operation over a known structure. A documentation tool's job is to explain code in prose — that's a generate operation from the code as input. The models are good at all three, but the failure modes differ, and the verification I owe each is different.

AI-powered code review: the find unit

AI code review uses ML models to analyze source code and surface bugs, security vulnerabilities, style violations, and performance issues [2]. The tools integrate into the pull-request workflow — a bot reads the diff and posts comments, much like a human reviewer, but immediately and on every change.

Where this shines is the high-frequency, low-subtlety review work that humans do poorly:

• Common bug patterns — null dereference, off-by-one, wrong comparison operator, unhandled error path.
• Security smells — SQL injection, hardcoded secrets, missing auth check, unsafe deserialization.
• Style and consistency — naming, complexity, dead code.

The model's value is that it reads everything, instantly, where a human reviewer skims. Its weakness is exactly that it's a pattern-matcher — it surfaces things that look like problems, which means false positives, and it can miss subtle architectural issues that require understanding the whole system. The right way of thinking: the AI is a tireless first-pass reviewer that catches the obvious stuff; the human reviewer is then free to focus on the hard, contextual questions.

The verification I owe its output: treat each comment as a hypothesis, not a finding. Some are real; some are the model pattern-matching on a false signal. I read each, fix the real ones, dismiss the rest, and never rubber-stamp its approval.

Refactoring with AI: the transform unit

Refactoring is restructuring code without changing its external behavior — simplifying complex logic, removing duplication, improving naming, extracting functions [3]. It's a high-value, high-tedium task: the improvement is clear, but the mechanical work is slow and error-prone. AI tools accelerate it by analyzing the code and suggesting (or implementing) improvements.

Where this shines is the preserving-behavior transforms that are easy to describe and tedious to do by hand:

• Extract function — pull a block into a named helper.
• Simplify conditional — collapse nested ifs, replace flag-driven logic with polymorphism.
• Rename consistently — change a name everywhere it appears.
• Modernize syntax — older patterns to newer equivalents (callbacks to async/await, var to let).

The model's value is speed — what took an hour now takes minutes, and the diff is reviewable. Its weakness is the same as any refactor: behavior must be preserved, and the model can subtly change semantics while restructuring. The verification I owe its output: tests. A refactor is safe only if the behavior is covered by tests that assert the same outcomes before and after. AI refactors without a test net are a coin flip — the model usually preserves behavior, but "usually" isn't a reliability claim I'll ship on.

Documentation generation: the generate unit

AI documentation generation analyzes code, comments, and project artifacts to produce API references, tutorials, and inline documentation [4]. The model reads the code and writes prose explaining what it does.

Where this shines is the documentation that should exist but doesn't because no one wants to write it:

• API reference — endpoint signatures, parameter descriptions, response shapes, often from an OpenAPI spec or route definitions.
• Function/method docs — summary of what a function does, its parameters and return value, from the signature and body.
• Onboarding summaries — high-level overviews of a module or subsystem.

The model's value is that the first draft, which is the hardest part of writing docs, becomes free. Its weakness is that the model describes what the code appears to do, which may not match intent — and AI-generated docs can be confidently wrong about why something exists. The verification I owe its output: a human who understands the intent reads and corrects the generated prose, especially the "why." The "what" is usually right; the "why" is where the model hallucinates.

The common thread: the verification obligation

What unifies all three is that the AI does the easy 80% instantly and leaves the hard 20% — the verification — to me. That ratio is the honest summary of AI in the development workflow. It is genuinely faster; it is not a replacement for judgment. The failure mode to avoid is treating AI output as authoritative because it reads fluently — fluent prose about a bug, a refactor, or an API can still be wrong, and shipping it unchecked moves the bug from "absent" to "documented."

The discipline I apply to all three:

• Read everything it produces. Skim is fine; rubber-stamp is not.
• Distinguish what from why. The model is reliable on what the code does; unreliable on why. Verify the why with a human or the code's history.
• Test before trusting transforms. Refactors are safe only with a test net. No tests, no AI refactor.
• Treat security findings as hypotheses. Confirm real ones; don't assume the model is right just because it sounds alarmed.

How I use this

Concretely, in my own workflow:

• Review — I run AI review tools on PRs before requesting human review. The first pass catches the obvious stuff; the human reviewer gets a cleaner diff and focuses on architecture.
• Refactor — I let AI do the mechanical refactors (extract, rename, modernize syntax), always behind tests. The complex architectural refactors I still drive myself, using AI as a pair.
• Docs — I generate API and function doc stubs from code, then edit them — especially to add the why the model can't infer.

The framing — find, transform, generate, each with its own verification — keeps me from over-trusting in one mode and under-using in another. The AI is a fast first draft across the development cycle; the human is still the one whose name is on the commit.

References

[1] IBM, "AI in software development," 2024. [Online]. Available: https://www.ibm.com/think/topics/ai-in-software-development

[2] GitHub, "AI Code Reviews." [Online]. Available: https://github.com/resources/articles/ai-code-reviews

[3] IBM, "What is AI code refactoring?," 2024. [Online]. Available: https://www.ibm.com/think/topics/ai-code-refactoring

[4] IBM, "AI code documentation: Benefits and top tips." [Online]. Available: https://www.ibm.com/think/insights/ai-code-documentation-benefits-top-tips