# 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