An AI Workflow for Software Development That Actually Holds Up
AI tools have moved on from autocomplete. Today's coding agents can read a whole repository, run commands, edit several files and check their own work. That's powerful, but it also means a vague request can turn into a large, confident, wrong change very quickly.
What made the difference for me wasn't a better model or a cleverer prompt. It was treating AI as one part of a workflow: a repeatable loop with clear inputs, small steps and checks at every stage. This post walks through that loop, then finishes with the advice I'd give anyone starting to build software this way.
The Loop at a Glance
- Context: write down how the project works, once.
- Plan: agree on what to build before any code is written.
- Build: make small, focused changes.
- Verify: let tests, types, linters and builds judge the result.
- Review: read the diff like you'd read a teammate's pull request.
- Ship and learn: commit, then feed what went wrong back into step 1.
None of these steps are new. They're ordinary engineering discipline. AI just makes skipping them much more expensive.
Step 1: Give the Project a Memory
An agent starts every session knowing nothing about your codebase's history. Without guidance it falls back on generic habits: the wrong package manager, an outdated framework API, copy hardcoded in a component instead of where your team keeps it.
The fix is a short instructions file in the repository, such as CLAUDE.md or AGENTS.md, that the agent reads automatically. Mine covers things like:
## Commands
- Use Yarn, not npm.
- Check a change with `yarn build` plus `npx eslint app components lib`.
## Where things live
- Copy and labels go in lib/constants.ts, not in components.
## Rules that are easy to break
- Dark mode is class-based. Don't use prefers-color-scheme in CSS.
- Accessibility is a requirement: labels, aria states, visible focus, AA contrast.
The best entries are the ones that would surprise a capable newcomer. You don't need to explain what React is. You do need to say "every database read in this project must be cached, and here's why." Every time the agent makes the same mistake twice, that's a line missing from this file.
Step 2: Plan Before You Generate
The most expensive AI mistake is a well-written solution to the wrong problem. For anything bigger than a small fix, I ask for a plan first and keep the agent from editing files until I've agreed to it:
"I want to add an RSS feed for blog posts. Don't write code yet.
Read how posts are loaded, then propose which files you'd add or change,
how caching would work, and anything you're unsure about."
A plan takes a minute to read and costs nothing to throw away. A 400-line diff built on a wrong assumption costs far more. The plan is also where the agent surfaces its open questions, and those are often the most useful part.
Step 3: Build in Small Slices
Agents are happy to change twenty files in one go. Resist it. Small slices are easier to review, easier to verify and easier to undo.
- One concern per task: "add the feed route", then "link it from the layout", not both at once.
- Start each larger task from a clean git state, so
git diffshows exactly what the agent did. - When a session wanders, start a fresh one with a clear summary rather than piling correction on correction.
Step 4: Let Tools Be the Judge
"It looks right" is not verification. The real advantage of an agent that can run commands is that it can check its own work against something objective. Give it a definition of done that a machine can confirm:
- Tests for behaviour. Writing a failing test first gives the agent a clear target and gives you proof it hit it.
- Type checks and linters for the whole class of small mistakes humans skim past.
- A production build, which catches framework rules a dev server might let slide.
- CI as the final gate, so nothing reaches the main branch on trust alone.
If an agent says something is fixed, ask how it knows. Good answers sound like "the build passes and the new test is green," not "this should work now."
Step 5: Review Like It's a Teammate's Pull Request
You are still the author of everything you merge. Read every diff, and read it with specific questions in mind:
- Does it follow the patterns already in the codebase, or invent new ones?
- Did it change anything it wasn't asked to touch?
- Are there quiet shortcuts: a disabled lint rule, a skipped test, an
anytype, a swallowed error? - Would I be able to explain this code to someone else tomorrow?
An AI review pass can help here as a second pair of eyes, but it supplements your review rather than replacing it.
Step 6: Close the Loop
After a task ships, spend thirty seconds on what went wrong. Did the agent use the wrong API? Miss a convention? Forget to run the build? Each of those is a sentence for the instructions file. Over a few weeks, that file turns into the most accurate onboarding document the project has, useful to new human teammates as much as to AI.
Connecting AI to Your Real Tools
Standards like the Model Context Protocol (MCP) let an assistant talk to the systems you already use: your CMS, issue tracker, database or design files. That's where workflows get really productive, and also where you need to be most careful. Give each connection the narrowest access it needs, prefer read-only where you can, and treat any action that publishes, deletes or messages people as something that needs your explicit approval.
My Advice for Working with AI
1. Own the Outcome
"The AI wrote it" is never an explanation for a bug in production. If you can't explain a change, don't merge it.
2. Keep Learning the Fundamentals
AI makes strong engineers faster because they can tell good output from bad. If you're early in your career, use it to explain and teach, not only to produce. Ask why a solution works, and occasionally write it yourself first and compare.
3. Be Specific, Then Be Patient
Say what you want, what you don't want, and how you'll judge the result. Then iterate. A targeted follow-up ("this misses the empty-list case") beats starting over.
4. Protect Secrets and Other People's Data
Never paste credentials, private keys or customer data into a tool you haven't vetted. Keep .env files out of anything an agent might send or commit, and check what your tools are allowed to access.
5. Slow Down Where Mistakes Are Expensive
Authentication, payments, data migrations, infrastructure and anything irreversible deserve line-by-line human review, whoever wrote the first draft. Speed is only worth having on work you can safely undo.
6. Measure the Real Gain
It's easy to feel productive watching code appear. The honest measure is whether features ship faster with fewer bugs. If you're spending more time fixing AI output than you saved, shrink the task size or improve your context file.
7. Know When to Close the Chat
Some problems are faster to solve by hand, and some decisions (architecture, product trade-offs, what to build at all) need judgment and context only you and your team have. Using AI well includes knowing when not to use it.
Summary
A good AI workflow looks a lot like a good engineering workflow, just with less room for shortcuts: write down the project's rules, plan before building, work in small slices, let tests and builds be the judge, review every diff and feed lessons back into your context. Treat the agent as a fast, tireless collaborator who needs clear direction and honest checking, and it will make you noticeably better at shipping software, not just faster at producing code.

