A Practical Workflow for Software Engineering with AI Agents

A vague feature request should not go directly into implementation.

First, establish a shared understanding of:

The user problem

Expected behavior

Technical constraints

Edge cases

Testing requirements

Explicitly excluded work

Existing modules affected by the change

This phase should remain human-led. Product owners, domain experts, and developers contribute information that cannot be inferred reliably from the repository.

The output is not code. It is a clear design concept shared by everyone involved.

The PRD describes the destination. It does not need to prescribe every implementation step.

A useful PRD contains:

The module list matters because the implementation must respect the existing system. A specification that ignores the codebase usually produces code that does not fit the codebase.

Avoid endlessly optimizing the document. Its purpose is to preserve the important decisions and provide enough direction for implementation.

Do not divide the work into separate database, API, and frontend phases.

That structure delays meaningful feedback until every layer has been completed. Problems between layers remain invisible for too long.

Instead, create vertical slices. Each issue should deliver a small piece of working behavior across the required layers.

For example:

This slice may include:

A database migration

A service method

Integration with lesson completion

A minimal dashboard component

Automated tests

The result is observable and testable. Later issues can extend the same path with levels, streaks, achievements, or historical data.

A sequential plan assumes that one agent completes every task in order. A dependency-aware backlog allows independent tasks to run in parallel.

Each issue should include:

The implementation system can then select any unblocked issue. Multiple isolated agents can work concurrently without guessing which tasks are safe to start.

Each implementation session should handle one coherent issue.

Long sessions accumulate stale assumptions, unrelated exploration, and previous mistakes. Smaller sessions give the agent a clearer objective and leave more context available for implementation and testing.

A bounded session follows this sequence:

1. Read the issue.

2. Inspect the relevant modules.

3. Write a failing test.

4. Implement the minimum required behavior.

5. Refactor the result.

6. Run the project’s feedback loops.

7. Commit the change.

The next issue starts with a clean context.

Test-driven development is particularly effective for automated implementation.

The agent writes a failing test before the implementation exists. It then adds code until the test passes. This makes it harder to write superficial tests that merely confirm code already produced.

The full feedback loop should include:

Unit or integration tests

Type checking

Linting

Builds

Database validation

Relevant end-to-end checks

The quality of these checks places a ceiling on implementation quality. An agent working without fast, reliable feedback is effectively coding blind.

Implementation and review should not share the same long context.

The implementation session already contains its own assumptions and decisions. A fresh reviewer can inspect the change independently and use its context for analysis instead of implementation history.

The review should receive:

The issue and acceptance criteria

The resulting diff

Project coding standards

Relevant architectural constraints

Test results

Review the tests first. Confirm that they exercise meaningful behavior. Then review the implementation behind them.

Automated review can catch defects, but it does not replace human code review or manual QA.

AI agents struggle in codebases made from many small files with complicated dependency relationships.

Prefer modules with:

A small public interface

Substantial internal behavior

Clear ownership

Strong test boundaries

Few external dependencies

Engineers should design and understand the module interfaces. The internal implementation can then be delegated more safely.

This preserves a useful mental model of the system. Developers understand what each module does and how modules interact without memorizing every implementation detail.

Planning, architecture, review, and QA require human judgment.

Implementation can often run unattended once the work is sufficiently clear and the repository provides reliable feedback. Human involvement returns when the result must be evaluated for correctness, usability, maintainability, and product quality.

The complete loop becomes:

The objective is not maximum code generation. It is a development system that produces reviewable changes while preserving engineering control.

[[Syncing Users Between Clerk and Your Database in Next.js]] is a concrete test of this workflow: concurrent requests, delayed events, and database failures need meaningful checks before an implementation can be trusted.

[[Monorepos: shared code, explicit boundaries]] considers the repository side of the same problem: shared code is easier to change safely when its interfaces, dependencies, and ownership are clear.