Devflow: A Four-Mode Workflow for AI-Assisted Programming

Devflow is a structured development workflow skill designed for AI agents. Through four modes—Design, Test, Implement, and Debug—it keeps AI-assisted coding purposeful and controllable. It addresses issues like deviation from expectations and repeated revisions caused by the lack of structure in current AI collaborative coding. By enforcing that only one mode is active at a time, it improves work quality and collaboration efficiency.

With the popularity of AI programming assistants like GitHub Copilot, Cursor, and Claude Code, collaborative coding between developers and AI has become the norm. However, such collaboration often lacks structure: under ambiguous requirements, AI-generated code easily deviates from expectations, leading to repeated revisions. In complex tasks, this unstructured mode results in insufficient architectural decisions, poor test coverage, inconsistent requirement understanding, and difficulty in locating root causes during debugging. The Devflow project was designed to address these issues with a structured workflow methodology.

Devflow divides development into four modes, enforcing that only one mode is active at a time and no switching is allowed without user consent:

Mode 1: Design

Goal: Clarify 'why to do it', 'what to do', and 'how to do it'. Deliver specifications that support test writing. Writing code is strictly prohibited.

Mode 2: Test (Red) — The Most Critical Mode

Goal: Prove that the specifications are testable. Write tests that only pass after correct implementation (covering main paths, boundaries, etc.). Deliver a test suite where all tests are red (due to assertion failures). Writing implementation code is strictly prohibited.

Mode 3: Implement (Green)

Goal: Make the red tests pass. Write implementation code. Modifying tests is strictly prohibited. Deliver all passing tests.

Mode 4: Observation and Debugging

Goal: Verify the system works end-to-end. Run coverage checks, write end-to-end tests. Write regression tests before fixing bugs. Deliver coverage reports, passing end-to-end tests, and zero known regressions.

Mode Switching Mechanism

At the end of each mode, a handoff document must be written in the root directory of the codebase (HANDOFF.md). It should include the mode name, goals, inputs, changes, outputs, unresolved issues, and recommended next mode. This solves the problem of context loss.

Heuristic Rules for Mode Recognition

Mode	Recognition Conditions
Design	No implementation plan exists, or the user requests planning/architecture
Test (Red)	Design is completed; no tests exist (or tests need to be written)
Implement (Green)	Failed tests exist; the task is to make them pass
Observation and Debugging	Tests pass; the task involves coverage, logging, or reported bugs

AI agents can automatically determine the mode, and users can also specify it directly.

For AI Agents

Provides a structured rhythm, clear completion standards, cross-session continuity, and an auditable decision-making process.

For Human Developers

Enforces design-first approach, strict TDD discipline, defensive debugging, and documented handoffs.

Comparison with Other Processes

Devflow is a workflow at the individual task execution level. It can be combined with project management methods like Agile and Scrum. It is orthogonal to branch management strategies like GitHub Flow and can be used complementarily.

Scenarios Excluded by Devflow:

• Exploratory programming (where requirements are uncertain and rapid prototyping is needed)
• Emergency hotfixes (the full process takes time)
• Pure refactoring tasks (no behavioral changes)

Applicable Scenarios: Typical tasks like feature development, MVP building, and bug fixes, which improve code quality and maintainability.

Devflow represents the trend of designing explicit workflows for AI-assisted programming. Drawing on mature practices like TDD, it provides a reference framework for AI collaboration. For developers using AI programming tools, it establishes a collaboration protocol, upgrading AI-assisted coding from 'casual chat' to 'structured collaboration'.