307 lines
4.9 KiB
Markdown
307 lines
4.9 KiB
Markdown
# 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
|
|
1. Understand the task
|
|
2. Identify affected files
|
|
3. Design the implementation
|
|
4. Implement step-by-step
|
|
5. 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:
|
|
|
|
1. analyze error message
|
|
2. inspect stack trace
|
|
3. identify root cause
|
|
4. implement fix
|
|
5. 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 |