---
title: "12 — AI in the Development Workflow — Reviews, Refactors, and Docs"
uid: ai-in-development-workflow
tags: ["refactoring", "workflow", "roadmap:backend", "documentation", "code-review", "ai", "productivity"]
excerpt: "Code review, refactoring, documentation generation: three distinct units of work — find, transform, generate. Each shines when scoped to its unit and disappoints when asked to do another's job."
date: 2026-08-13T03:28:25+0000
source: https://www.aveshina.my.id/en/blog/ai-in-development-workflow
---

"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](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](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](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](https://www.ibm.com/think/insights/ai-code-documentation-benefits-top-tips)

```quiz
Q: The three AI development touchpoints map to three different units of work. Which mapping is correct?
- Review = find; refactoring = transform; documentation = generate
- Review = generate; refactoring = find; documentation = transform
correct: 0
explain: Review detects issues in existing code (find). Refactoring restructures code preserving behavior (transform). Documentation produces prose from code (generate). Each is a different unit with different failure modes and verification.

Q: What is the main weakness of AI-powered code review?
- It pattern-matches, producing false positives and missing subtle architectural issues requiring whole-system understanding
- It cannot read any code written in dynamically-typed languages
correct: 0
explain: The model surfaces things that look like problems, so false positives occur, and it struggles with subtle architectural issues that need system-wide context. Its value is tireless first-pass coverage; the human reviewer still handles the hard, contextual questions.

Q: Why are tests a prerequisite for trusting an AI-suggested refactor?
- A refactor is safe only if behavior is preserved; tests assert the same outcomes before and after. AI can subtly change semantics while restructuring
- Tests make the refactor run faster
correct: 0
explain: Refactoring preserves external behavior by definition. Tests verify that. AI can subtly alter semantics while restructuring, so without a test net an AI refactor is a coin flip. No tests, no AI refactor.

Q: AI-generated documentation tends to be reliable on which aspect, and unreliable on which?
- Reliable on what the code does; unreliable on why it exists
- Reliable on why the code exists; unreliable on what it does
correct: 0
explain: The model reads the code and describes what it does competently. But intent — why a design choice was made — requires context the code alone doesn't carry. Always verify the why with a human or the code's history.

Q: What is the honest ratio that summarizes AI in the development workflow?
- AI does the easy 80% instantly; the hard 20% (verification) is still human
- AI does 100% of the work and humans only deploy it
correct: 0
explain: AI genuinely accelerates the first draft across review, refactor, and docs. But fluent output can still be wrong. The verification obligation — reading, testing, correcting intent — is unchanged. Shipping AI output unchecked moves bugs from absent to documented.
```