203 lines
4.2 KiB
Markdown
203 lines
4.2 KiB
Markdown
# cd-browser AI Development Playbook
|
||
|
||
Author: Saky\
|
||
Purpose: Reusable methodology for building software with AI coding
|
||
agents.
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 1. Philosophy
|
||
|
||
This playbook documents a repeatable workflow for building software with
|
||
AI agents such as:
|
||
|
||
- OpenCode
|
||
- Codex‑style coding agents
|
||
- LLM programming assistants
|
||
|
||
Goal:
|
||
|
||
Maintain **architectural control and code quality** while benefiting
|
||
from AI‑accelerated development.
|
||
|
||
Core principle:
|
||
|
||
AI is used as an **implementation engine**, not as an architect.
|
||
|
||
The human defines:
|
||
|
||
- architecture
|
||
- boundaries
|
||
- specifications
|
||
- validation rules
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 2. The AI Development Workflow
|
||
|
||
The method used in the `cd-browser` project follows this sequence:
|
||
|
||
Specification → Architecture → Module Scaffolding → Implementation →
|
||
Validation → Integration → Release
|
||
|
||
Each step uses **focused prompts with limited scope**.
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 3. Repository Preparation
|
||
|
||
Before using an AI coding agent, the repository must define:
|
||
|
||
## Tooling
|
||
|
||
black -- formatting\
|
||
ruff -- linting\
|
||
mypy -- type checking\
|
||
pytest -- testing\
|
||
pre-commit -- commit validation
|
||
|
||
## Folder structure
|
||
|
||
src/ tests/ specs/ scripts/ docs/
|
||
|
||
## AI agent rules
|
||
|
||
Defined in:
|
||
|
||
instructions-agent.md
|
||
|
||
The file instructs the agent to:
|
||
|
||
- read specifications first
|
||
- reuse modules
|
||
- keep changes minimal
|
||
- run validation workflows
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 4. Prompt Design Principles
|
||
|
||
Effective prompts follow three rules:
|
||
|
||
### 1. Limit scope
|
||
|
||
Always define affected files.
|
||
|
||
Example:
|
||
|
||
Scope: - src/app/navigator.py - tests/test_navigator.py
|
||
|
||
### 2. Define constraints
|
||
|
||
Example:
|
||
|
||
Do not implement UI yet.
|
||
|
||
### 3. Require validation
|
||
|
||
Example:
|
||
|
||
Run:
|
||
|
||
make fix\
|
||
make quality
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 5. Example Prompt --- Module Implementation
|
||
|
||
Example used in the project:
|
||
|
||
Implement navigator state model.
|
||
|
||
Scope: - src/app/navigator.py - tests related to navigator behavior
|
||
|
||
Requirements: - track current path - manage selection - support
|
||
expansion and collapse - integrate history module - add pytest coverage
|
||
|
||
Validation: - make fix - make quality
|
||
|
||
Output: - files changed - summary of implementation
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 6. Example Prompt --- Debugging
|
||
|
||
Example debugging prompt used:
|
||
|
||
We discovered a terminal integration issue.
|
||
|
||
Problem: The shell wrapper captures stdout using command substitution.
|
||
The curses UI fails when stdout is captured.
|
||
|
||
Requirements: - attach UI to /dev/tty - ensure stdout prints only final
|
||
path - move logs to stderr
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 7. Prompt Template
|
||
|
||
Reusable template:
|
||
|
||
Scope: (list files)
|
||
|
||
Requirements: (describe expected behaviour)
|
||
|
||
Constraints: (limit unwanted features)
|
||
|
||
Validation: (run project tooling)
|
||
|
||
Output: (files changed + summary)
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 8. Validation Loop
|
||
|
||
Every change follows the validation loop:
|
||
|
||
1. Agent implements change
|
||
2. Run:
|
||
|
||
make fix make quality
|
||
|
||
3. Review output
|
||
4. Commit if successful
|
||
|
||
This guarantees stable incremental development.
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 9. Best Practices
|
||
|
||
✔ Keep prompts small\
|
||
✔ Implement one module at a time\
|
||
✔ Always request tests\
|
||
✔ Run automated checks\
|
||
✔ Separate specification from implementation
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 10. Anti‑Patterns
|
||
|
||
Avoid:
|
||
|
||
❌ large prompts implementing entire applications\
|
||
❌ vague requirements\
|
||
❌ skipping validation steps\
|
||
❌ allowing the AI to define architecture
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# 11. Benefits
|
||
|
||
Using this workflow:
|
||
|
||
- reduces implementation time
|
||
- preserves architectural control
|
||
- ensures consistent code quality
|
||
- enables reproducible development
|
||
|
||
------------------------------------------------------------------------
|
||
|
||
# End
|