agentic-development-principles

What this skill does

# Agentic development principles (Agentic Development Principles)

> **"AI is the copilot; you are the pilot"**
> AI agents amplify the developer's thinking and take over repetitive work, but final decision-making authority and responsibility always remain with the developer.

## When to use this skill

- When starting a collaboration session with an AI agent
- When deciding an approach before starting a complex task
- When establishing a context management strategy
- When reviewing workflows to improve productivity
- When onboarding teammates on how to collaborate with AI
- When applying baseline principles while adopting a new AI tool

---

## Principle 1: Divide and conquer (Divide and Conquer)

### Core concept
AI performs much better with **small, clear instructions** than with large, ambiguous tasks.

### How to apply

| Wrong example | Right example |
|----------|----------|
| "Build me a login page" | 1. "Create the login form UI component" |
| | 2. "Implement the login API endpoint" |
| | 3. "Wire up the authentication logic" |
| | 4. "Write test code" |
| "Optimize the app" | 1. "Analyze performance bottlenecks" |
| | 2. "Optimize database queries" |
| | 3. "Reduce frontend bundle size" |

### Practical pattern: staged implementation

```
Step 1: Design and validate the model/schema
Step 2: Implement core logic (minimum viable functionality)
Step 3: Connect APIs/interfaces
Step 4: Write and run tests
Step 5: Integrate and refactor
```

### Validation points
- [ ] Can each step be validated independently?
- [ ] If it fails, can you fix only that step?
- [ ] Is the scope clear enough for the AI to understand?

---

## Principle 2: Context is like milk (Context is like Milk)

### Core concept
Context (the AI's working memory) should always be kept **fresh and compact**.
- Old and irrelevant information reduces AI performance
- Context drift: mixing multiple topics can reduce performance by up to 39% (research)

### Context management strategies

#### Strategy 1: Single-purpose conversation
```
Session 1: Work on the authentication system
Session 2: Work on UI components  
Session 3: Write test code
Session 4: DevOps/deployment work
```
- Do not mix multiple topics in a single conversation
- Start a new session for a new topic

#### Strategy 2: HANDOFF.md technique
When the conversation gets long, summarize only the essentials and hand them to a new session:

```markdown
# HANDOFF.md

## Completed work
- ✅ Implemented user authentication API
- ✅ Implemented JWT token issuance logic

## Current status
- Working on token refresh logic

## Next tasks
- Implement refresh tokens
- Add logout endpoint

## Tried but failed
- Failed to integrate Redis session store (network issue)

## Cautions
- Watch for conflicts with existing session management code
```

#### Strategy 3: Monitor context state
- When the conversation gets long, ask the AI to summarize the current state
- If needed, reset the conversation and restart using HANDOFF.md

#### Strategy 4: Optimization metrics
| Metric | Recommended value | Action |
|------|---------|------|
| Conversation length | Keep to a reasonable level | Create HANDOFF.md if it gets long |
| Topic count | 1 (single purpose) | Use a new session for new topics |
| Active files | Only what's needed | Remove unnecessary context |

---

## Principle 3: Choose the right abstraction level

### Core concept
Choose an appropriate abstraction level depending on the situation.

| Mode | Description | When to use |
|------|------|----------|
| **Vibe Coding** | High level (see only overall structure) | Rapid prototyping, idea validation, one-off projects |
| **Deep Dive** | Low level (go line-by-line) | Bug fixes, security review, performance optimization, production code |

### In practice

```
When adding a new feature:
1. High abstraction: "Create a user profile page" → understand overall structure
2. Medium abstraction: "Show the validation logic for the profile edit form" → review a specific feature
3. Low abstraction: "Explain why this regex fails email validation" → detailed debugging
```

### Abstraction level selection guide
- **Prototype/PoC**: Vibe Coding 80%, Deep Dive 20%
- **Production code**: Vibe Coding 30%, Deep Dive 70%
- **Bug fixes**: Deep Dive 100%

---

## Principle 4: Automation of automation (Automation of Automation)

### Core concept
```
If you've repeated the same task 3+ times → find a way to automate it
And the automation process itself → automate that too
```

### Automation level evolution

| Level | Approach | Example |
|-------|------|------|
| 1 | Manual copy/paste | AI output → copy into terminal |
| 2 | Terminal integration | Use AI tools directly |
| 3 | Voice input | Voice transcription system |
| 4 | Automate repeated instructions | Use project config files |
| 5 | Workflow automation | Custom commands/scripts |
| 6 | Automate decisions | Use Skills |
| 7 | Enforce rules automatically | Use hooks/guardrails |

### Checklist: identify automation targets
- [ ] Do you run the same command 3+ times?
- [ ] Do you repeat the same explanations?
- [ ] Do you often write the same code patterns?
- [ ] Do you repeat the same validation procedures?

### Automation priority
1. **High**: tasks repeated daily
2. **Medium**: tasks repeated weekly (or more)
3. **Low**: tasks repeated about once a month

---

## Principle 5: Balance caution and speed (Plan vs Execute)

### Plan mode (Plan Mode)
Analyze without executing; execute only after review/approval

**When to use:**
- A complex task you're doing for the first time
- A large refactor spanning multiple files
- Architecture changes
- Database migrations
- Hard-to-roll-back work

### Execute mode (Execute Mode)
AI directly edits code and runs commands

**When to use:**
- Simple, clear tasks
- Work with well-validated patterns
- Sandbox/container environments
- Easy-to-revert work

### Recommended ratio
- Plan mode: **70-90%** (use as the default)
- Execute mode: **10-30%** (only in safe environments)

### Safety principles
- ⚠️ Auto-running dangerous commands only in isolated environments
- Always back up before changing important data
- Always use plan mode for irreversible work

---

## Principle 6: Verify and reflect (Verify and Reflect)

### How to verify output

1. **Write test code**
   ```
   "Write tests for this function. Include edge cases too."
   ```

2. **Visual review**
   - Review changed files via diff
   - Revert unintended changes

3. **Draft PR / code review**
   ```
   "Create a draft PR for these changes"
   ```

4. **Ask for self-verification**
   ```
   "Review the code you just generated again.
   Validate every claim, and summarize the verification results in a table at the end."
   ```

### Verification checklist
- [ ] Does the code work as intended?
- [ ] Are edge cases handled?
- [ ] Are there any security vulnerabilities?
- [ ] Are tests sufficient?
- [ ] Are there any performance issues?

### Reflection questions
- What did you learn in this session?
- What could you do better next time?
- Were there repetitive tasks you could automate?

---

## Quick Reference

### Six principles summary

| Principle | Core | Practice |
|------|------|------|
| 1. Divide and conquer | Small, clear units | Split into independently verifiable steps |
| 2. Context management | Keep it fresh | Single-purpose conversations, HANDOFF.md |
| 3. Abstraction choice | Depth per situation | Adjust Vibe ↔ Deep Dive |
| 4. Automation² | Remove repetition | Automate after 3 repetitions |
| 5. Plan/execute balance | Caution first | Plan 70-90%, execute 10-30% |
| 6. Verification/reflection | Check outputs | Tests, reviews, self-verification |

### Mastery rule
> "To truly master AI tools, you need to use them enough"

Learning by using is key - theory alone is not enough; you need to experience different situations in real projects.

### Golden rule
```
When instructing an AI:
1. Clearly (Specific)
2. Step-by-step (Step-by-step)
3. Verifiable (Verifiabl