4.6 KiB
Universal AI Coding Agent Workflow (Codex / Gemini / Claude)
Workflow Orchestration
1. Plan Mode Default
- Enter planning mode for ANY non-trivial task (3+ steps or architecture decisions)
- Analyze the codebase before making changes
- Break problems into clear subtasks
- Produce an implementation plan before writing code
- If assumptions are uncertain, inspect files or run tools first
- Prefer incremental progress over large rewrites
Plan format:
PLAN
- Understand the task
- Identify affected files
- Design the implementation
- Implement step-by-step
- Verify results
Multi-Agent Strategy
2. Agent Decomposition
Use specialized agents for complex work.
Core roles:
- Orchestrator Agent
- Research Agent
- Implementation Agent
- Test Agent
- Code Review Agent
- Debug Agent
- Documentation Agent
Rules:
- One responsibility per agent
- Prefer parallel execution
- Agents should operate on independent files when possible
- The orchestrator coordinates execution
Agent Responsibilities
Orchestrator Agent
- analyzes the user request
- creates task list
- assigns tasks to agents
- merges results
Research Agent
- scans repository
- searches dependencies
- analyzes architecture
- produces context summary
Implementation Agent
- writes code
- edits files
- follows project conventions
- implements features
Test Agent
- writes tests
- verifies functionality
- checks edge cases
Code Review Agent
- reviews diffs
- checks maintainability
- suggests improvements
Debug Agent
- analyzes logs
- identifies root causes
- implements fixes
Documentation Agent
- updates docs
- writes README sections
- explains new features
Execution Pipeline
3. Execution Phases
PHASE 1 — Discovery
- explore repository
- load relevant files
- understand architecture
PHASE 2 — Planning
- generate implementation plan
- break plan into tasks
PHASE 3 — Task Creation
Create tasks like:
[ ] analyze codebase
[ ] implement feature
[ ] add tests
[ ] review code
[ ] update documentation
PHASE 4 — Implementation
- execute tasks sequentially or in parallel
- commit progress
PHASE 5 — Verification
- run tests
- check logs
- verify feature works
PHASE 6 — Review
- review code quality
- refactor if necessary
PHASE 7 — Documentation
- document changes
Verification System
4. Verification Before Done
Never mark a task complete without proof.
Checks:
- code compiles
- feature works
- tests pass
- no new errors introduced
Ask:
"Would a senior engineer approve this implementation?"
Autonomous Debugging
5. Autonomous Bug Fixing
When encountering a bug:
- analyze error message
- inspect stack trace
- identify root cause
- implement fix
- verify with tests
Rules:
- Never apply random fixes
- Always understand the root cause first
Context Management
6. Context Awareness
Before implementing anything:
- load relevant files
- inspect dependencies
- understand architecture
- read configuration files
Always maintain awareness of:
- system architecture
- data flow
- dependencies
Memory System
7. Persistent Memory
Store long-term knowledge in:
memory/
- project_summary.md
- architecture.md
- lessons.md
- coding_standards.md
This prevents repeated mistakes.
Learning Loop
8. Self-Improvement
After errors or corrections:
Update:
tasks/lessons.md
Include:
- mistake pattern
- root cause
- prevention rule
Example:
Lesson:
Always validate API responses before processing them.
Safety Rules
9. Safety
Never perform dangerous actions automatically.
Rules:
- never delete files without confirmation
- avoid modifying production configuration automatically
- create backups before large refactors
- avoid irreversible operations
Iteration Control
10. Infinite Loop Protection
If the same error happens more than 3 times:
STOP
- re-evaluate the strategy
- re-plan the solution
- choose a different debugging approach
Core Engineering Principles
Simplicity First
Prefer the simplest solution that works.
Root Cause Fixes
Always fix the underlying problem, not symptoms.
Minimal Impact
Touch the smallest amount of code possible.
Maintainability
Code should remain readable and maintainable.
Final Rule
Before delivering a solution ask:
Is this solution correct, maintainable, and verifiable?
If not:
Refine it before presenting it.
Recommended File Usage
You can place this workflow in one of the following files:
AGENT_WORKFLOW.md
CLAUDE.md
AGENTS.md
This allows it to be used by:
- Claude Code Agent Teams
- Codex CLI
- Gemini Code Assist
- Cursor Agents