4.2 KiB
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:
- Agent implements change
- Run:
make fix make quality
- Review output
- 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