Initial commit
This commit is contained in:
Zhongwei Li
300
skills/adw-bootstrap/docs/principles.md
Normal file
300
skills/adw-bootstrap/docs/principles.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# AI Developer Workflows (ADWs): Core Principles
|
||||
|
||||
## What Are ADWs?
|
||||
|
||||
**AI Developer Workflows (ADWs)** are executable scripts that combine deterministic code with non-deterministic, compute-scalable AI agents to perform complex development tasks programmatically.
|
||||
|
||||
Instead of directly modifying code yourself, you **template your engineering patterns** and **teach agents how to operate your codebase**. This allows you to scale impact by scaling compute, not just effort.
|
||||
|
||||
## The Two-Layer Architecture
|
||||
|
||||
### Agentic Layer
|
||||
**Purpose**: Template engineering patterns and teach agents how to operate
|
||||
|
||||
**Components**:
|
||||
- `adws/` - AI Developer Workflow scripts and modules
|
||||
- `.claude/` - Slash commands, skills, hooks, agent configurations
|
||||
- `specs/` - Implementation plans and specifications
|
||||
- `agents/` - Agent execution outputs (observability)
|
||||
|
||||
**Role**: Provides the programmatic interface for AI-driven development
|
||||
|
||||
### Application Layer
|
||||
**Purpose**: The actual application code that agents operate on
|
||||
|
||||
**Components**:
|
||||
- `apps/`, `src/`, `lib/`, etc. - Your application code
|
||||
- `tests/` - Your test suites
|
||||
- Application-specific configuration and resources
|
||||
|
||||
**Role**: What the agents modify, test, and deploy
|
||||
|
||||
## The 12 Leverage Points of Agentic Coding
|
||||
|
||||
### In Agent (Core Four)
|
||||
These directly control agent behavior during execution:
|
||||
|
||||
1. **Context** - What information the agent has access to
|
||||
2. **Model** - Which AI model processes the prompt (Sonnet vs Opus)
|
||||
3. **Prompt** - The specific instructions given to the agent
|
||||
4. **Tools** - What actions the agent can take (Read, Write, Bash, etc.)
|
||||
|
||||
### Through Agent (Structural Eight)
|
||||
These shape how you structure work for agents:
|
||||
|
||||
5. **Standard Output** - Structured agent outputs for observability
|
||||
6. **Types** - Data models and schemas that define interfaces
|
||||
7. **Docs** - Documentation that provides context to agents
|
||||
8. **Tests** - Validation that ensures agent work is correct
|
||||
9. **Architecture** - System design that guides agent decisions
|
||||
10. **Plans** - Specifications that break work into steps
|
||||
11. **Templates** - Reusable prompt patterns (slash commands)
|
||||
12. **AI Developer Workflows** - Orchestrated multi-agent processes
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: Subprocess-Based Execution
|
||||
|
||||
**When to use**: Simple prompts, shell compatibility, lower dependencies
|
||||
|
||||
```python
|
||||
from agent import prompt_claude_code, AgentPromptRequest
|
||||
|
||||
request = AgentPromptRequest(
|
||||
prompt="Analyze this module",
|
||||
adw_id="abc12345",
|
||||
agent_name="analyzer",
|
||||
model="sonnet",
|
||||
output_file="agents/abc12345/analyzer/cc_raw_output.jsonl"
|
||||
)
|
||||
|
||||
response = prompt_claude_code(request)
|
||||
if response.success:
|
||||
print(response.output)
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- Invokes Claude Code CLI as subprocess
|
||||
- Streams output to JSONL files
|
||||
- Parses results into structured JSON
|
||||
- Implements retry logic for transient failures
|
||||
- Works with both subscription and API modes
|
||||
|
||||
### Pattern 2: SDK-Based Execution
|
||||
|
||||
**When to use**: Interactive sessions, better type safety, async workflows
|
||||
|
||||
```python
|
||||
from agent_sdk import simple_query
|
||||
|
||||
response = await simple_query("Implement feature X")
|
||||
print(response)
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- Native Python async/await
|
||||
- Typed message objects
|
||||
- SDK-specific error handling
|
||||
- Interactive session support
|
||||
- Better IDE integration
|
||||
|
||||
### Pattern 3: Template-Based Development
|
||||
|
||||
**Slash commands** are reusable prompt templates:
|
||||
|
||||
```markdown
|
||||
# .claude/commands/chore.md
|
||||
Create a plan using this format:
|
||||
|
||||
## Variables
|
||||
adw_id: $1
|
||||
description: $2
|
||||
|
||||
## Instructions
|
||||
1. Analyze the codebase starting with README.md
|
||||
2. Create a step-by-step plan
|
||||
3. Save to specs/chore-{adw_id}-{name}.md
|
||||
```
|
||||
|
||||
Execute: `./adws/adw_slash_command.py /chore abc123 "add logging"`
|
||||
|
||||
### Pattern 4: Workflow Orchestration
|
||||
|
||||
**Compound workflows** chain multiple agent invocations:
|
||||
|
||||
```python
|
||||
# Phase 1: Planning
|
||||
chore_response = execute_template(
|
||||
slash_command="/chore",
|
||||
args=[adw_id, description]
|
||||
)
|
||||
|
||||
# Extract plan path from response
|
||||
plan_path = extract_plan_path(chore_response.output)
|
||||
|
||||
# Phase 2: Implementation
|
||||
implement_response = execute_template(
|
||||
slash_command="/implement",
|
||||
args=[plan_path]
|
||||
)
|
||||
```
|
||||
|
||||
## Observability First
|
||||
|
||||
Every ADW execution creates structured outputs:
|
||||
|
||||
```
|
||||
agents/{adw_id}/{agent_name}/
|
||||
cc_raw_output.jsonl # Raw streaming JSONL
|
||||
cc_raw_output.json # Parsed JSON array
|
||||
cc_final_object.json # Final result object
|
||||
custom_summary_output.json # High-level summary
|
||||
```
|
||||
|
||||
**Why this matters**:
|
||||
- Debug agent behavior by reading raw outputs
|
||||
- Programmatically process results from JSON
|
||||
- Track lineage with unique IDs
|
||||
- Audit what agents did and why
|
||||
|
||||
## Progressive Enhancement
|
||||
|
||||
Start simple, add complexity as needed:
|
||||
|
||||
### Minimal (Always)
|
||||
- Core subprocess execution (`agent.py`)
|
||||
- Basic prompt wrapper (`adw_prompt.py`)
|
||||
- Essential slash commands (chore, implement)
|
||||
- Spec directory for plans
|
||||
|
||||
**Good for**: Proof of concepts, simple automation, getting started
|
||||
|
||||
### Enhanced (Recommended)
|
||||
- SDK support (`agent_sdk.py`)
|
||||
- Compound workflows (`adw_chore_implement.py`)
|
||||
- Rich slash commands (feature, test, prime)
|
||||
- Slash command executor
|
||||
|
||||
**Good for**: Active development, team collaboration, feature automation
|
||||
|
||||
### Scaled (Production)
|
||||
- State management across phases
|
||||
- Git worktree isolation
|
||||
- Trigger systems (webhooks, cron)
|
||||
- Testing infrastructure
|
||||
- Comprehensive observability
|
||||
|
||||
**Good for**: Production systems, enterprise teams, complex SDLC
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Environment Safety
|
||||
```python
|
||||
# Filter environment variables
|
||||
def get_safe_subprocess_env():
|
||||
return {
|
||||
"ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
|
||||
"HOME": os.getenv("HOME"),
|
||||
"PATH": os.getenv("PATH"),
|
||||
# Only essential variables
|
||||
}
|
||||
```
|
||||
|
||||
**Why**: Prevents environment variable leakage, security isolation
|
||||
|
||||
### 2. Retry Logic
|
||||
```python
|
||||
def prompt_claude_code_with_retry(request, max_retries=3):
|
||||
for attempt in range(max_retries + 1):
|
||||
response = prompt_claude_code(request)
|
||||
if response.success or response.retry_code == RetryCode.NONE:
|
||||
return response
|
||||
time.sleep(retry_delays[attempt])
|
||||
```
|
||||
|
||||
**Why**: Handle transient failures (network issues, rate limits, timeouts)
|
||||
|
||||
### 3. Error Truncation
|
||||
```python
|
||||
def truncate_output(output, max_length=500):
|
||||
if len(output) <= max_length:
|
||||
return output
|
||||
return output[:max_length-15] + "... (truncated)"
|
||||
```
|
||||
|
||||
**Why**: Prevent console flooding from huge error messages
|
||||
|
||||
### 4. Unique ID Tracking
|
||||
```python
|
||||
def generate_short_id():
|
||||
return str(uuid.uuid4())[:8]
|
||||
|
||||
adw_id = generate_short_id() # abc12345
|
||||
# All outputs go to: agents/abc12345/
|
||||
```
|
||||
|
||||
**Why**: Track execution lineage, associate outputs, debug flows
|
||||
|
||||
### 5. Type Safety
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AgentPromptRequest(BaseModel):
|
||||
prompt: str
|
||||
adw_id: str
|
||||
model: Literal["sonnet", "opus"]
|
||||
output_file: str
|
||||
```
|
||||
|
||||
**Why**: Catch errors early, better IDE support, self-documenting
|
||||
|
||||
## Usage Modes
|
||||
|
||||
### Mode A: Claude Max Subscription
|
||||
- User has Claude Max subscription
|
||||
- No API key needed
|
||||
- Claude Code authenticates through subscription
|
||||
- Perfect for interactive development
|
||||
|
||||
### Mode B: API-Based Automation
|
||||
- Requires `ANTHROPIC_API_KEY`
|
||||
- Enables headless automation
|
||||
- Required for CI/CD, webhooks, cron jobs
|
||||
- Programmatic agent execution
|
||||
|
||||
**Both modes work with the same ADW infrastructure.** The code detects which mode to use automatically.
|
||||
|
||||
## Philosophy: Scale Compute, Not Just Effort
|
||||
|
||||
Traditional development: **You write the code**
|
||||
- Linear scaling: More features = more time
|
||||
- Bottleneck: Your available hours
|
||||
- Hard to parallelize
|
||||
|
||||
Agentic development: **You template patterns, agents write the code**
|
||||
- Compute scaling: More features = more parallel agents
|
||||
- Bottleneck: Compute availability
|
||||
- Easy to parallelize
|
||||
|
||||
**This is the fundamental shift.** ADWs enable this paradigm.
|
||||
|
||||
## Key Insights
|
||||
|
||||
1. **Separation of Concerns**: Agentic layer (how to operate) vs Application layer (what to operate on)
|
||||
|
||||
2. **Progressive Enhancement**: Start minimal, add features as needed, scale when required
|
||||
|
||||
3. **Observability**: Structured outputs make agent behavior transparent and debuggable
|
||||
|
||||
4. **Intelligence Over Templating**: Provide patterns, let Claude adapt intelligently
|
||||
|
||||
5. **Mode Flexibility**: Support both interactive (subscription) and automated (API) workflows
|
||||
|
||||
6. **Compute as Leverage**: Scale impact by scaling compute, not just working harder
|
||||
|
||||
## Further Reading
|
||||
|
||||
- `architecture.md` - Detailed architecture patterns
|
||||
- `usage-modes.md` - Deep dive on subscription vs API modes
|
||||
- Reference implementations in `reference/` directory
|
||||
- Main skill logic in `SKILL.md`
|
||||
Reference in New Issue
Block a user