菜单
Hierarchical content structure - answer first, then supporting arguments, then details
| name | pyramid-principle |
| description | Hierarchical content structure - answer first, then supporting arguments, then details |
| foundation | Barbara Minto's Pyramid Principle |
| use_case | Outlines, business communication, structured explanations |
Foundation: Barbara Minto's pyramid principle for clear, logical communication
Core Concept: Start with the answer, then provide supporting arguments, then add details.
Why This Works:
[ANSWER / Core Message]
|
┌──────────────────┼──────────────────┐
| | |
[Argument 1] [Argument 2] [Argument 3]
| | |
┌───┼───┐ ┌───┼───┐ ┌───┼───┐
| | | | | | | | |
[Details] [Details] [Details] [Details] [Details] [Details]
Levels:
Always start with the conclusion
❌ Don't do this (bottom-up):
We analyzed 10 frameworks. We tested each for 6 months.
We measured productivity, reliability, and ease of use.
Framework X performed best. Therefore, we recommend Framework X.
✅ Do this (top-down):
**We recommend Framework X** because it delivers 30% higher productivity
with proven reliability over 6 months of testing.
Here's why:
1. Productivity: 30% improvement vs alternatives
2. Reliability: Zero critical failures in production
3. Ease of adoption: 2-week learning curve vs 2-month for alternatives
Why: Reader knows the answer immediately. Supporting details provide confidence, but aren't prerequisite to understanding recommendation.
Ideas in each group must be:
✅ Good grouping:
Core Message: "CAF transforms Claude Code into domain-specific agents"
├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)
├─ Argument 2: Domain transformation examples
└─ Argument 3: Proven patterns and constraints
❌ Bad grouping (mixed levels):
Core Message: "CAF transforms Claude Code into domain-specific agents"
├─ Argument 1: Customization spectrum
├─ Argument 2: File-based persistence (this is a detail, not major argument)
└─ Argument 3: Stefan uses it for ML4T book (this is an example, not argument)
Arguments must follow logical sequence:
Structural order: Parts of something
Chronological order: Time sequence
Comparative order: Ranking or comparison
Problem-solution order: Issue then resolution
Structure:
# Outline
## Opening (Level 1: Answer)
- Hook (grab attention)
- Core message (the answer)
- Preview (what's coming)
## Body (Level 2: Arguments)
### Argument 1: [First supporting point]
- Evidence (Level 3)
- Examples (Level 3)
- Details (Level 4)
### Argument 2: [Second supporting point]
- Evidence (Level 3)
- Examples (Level 3)
- Details (Level 4)
### Argument 3: [Third supporting point]
- Evidence (Level 3)
- Examples (Level 3)
- Details (Level 4)
## Closing (Level 1: Reinforce Answer)
- Restate core message
- Call to action
Example for CAF white paper:
Opening: "Transform Claude Code into specialized domain agents"
├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)
│ ├─ Evidence: What each level provides
│ ├─ Example: Content management workflow
│ └─ Details: When to use each level
├─ Argument 2: Domain transformation mechanism
│ ├─ Evidence: How markdown customization works
│ ├─ Example: Commands, agents, skills
│ └─ Details: Technical architecture
└─ Argument 3: Proven patterns and constraints
├─ Evidence: 6 months production use
├─ Example: Specific patterns
└─ Details: How constraints prevent failure
Closing: Reinforce transformation message + CTA
Memo structure:
Subject: Recommendation
**Recommendation**: [The answer - one sentence]
**Rationale**: [3-5 supporting arguments]
1. Argument 1
2. Argument 2
3. Argument 3
**Details**: [Evidence for each argument]
[Expand on arguments with data, examples, elaboration]
Why this works: Executive reads first line, gets answer, decides if they need to read more.
Explain "What is CAF?":
❌ Bottom-up (reader lost):
Claude Code has plugins. Plugins have commands. Commands invoke agents.
Agents use skills. Skills provide patterns. Patterns create frameworks.
Therefore, CAF is a meta-framework for domain-specific agent customization.
✅ Top-down (pyramid):
**CAF transforms Claude Code into domain-specific agents through markdown-based customization.**
How it works:
1. Commands: Encapsulate domain workflows
2. Agents: Provide specialized capabilities
3. Skills: Define behavior patterns
Why it matters:
- Transforms generic AI into domain-expert
- Uses simple markdown (no coding required)
- Proven patterns prevent common failures
Reader benefit: Understands "what it is" immediately, can drill into details if interested.
❌ Don't hide the answer:
We conducted extensive research. We analyzed frameworks.
We tested implementations. We gathered feedback.
After 6 months, we discovered that...
✅ Answer first:
**CAF prevents AI chaos through stateless, file-based architecture.**
Evidence from 6 months testing:
- Zero state corruption failures
- 100% reproducible results
- Context preserved across sessions
❌ Arguments at different levels:
1. Customization spectrum (high-level concept)
2. File-based persistence (implementation detail)
3. Domain transformation (high-level concept)
✅ Same level:
1. Customization spectrum (what CAF provides)
2. Domain transformation (how it works)
3. Proven patterns (why it's reliable)
❌ Random order:
1. Benefits
2. How it works
3. What it is
✅ Logical order:
1. What it is (establish understanding)
2. How it works (explain mechanism)
3. Benefits (show value)
❌ Flat list:
- Point 1
- Point 2
- Point 3
- Point 4
- Point 5
(All at same level, no structure)
✅ Hierarchical:
Core Message
├─ Major Point 1
│ ├─ Supporting detail
│ └─ Example
├─ Major Point 2
│ ├─ Supporting detail
│ └─ Example
└─ Major Point 3
├─ Supporting detail
└─ Example
When applying pyramid principle, verify:
Pyramid + excellent-writing:
Pyramid + SCQA:
Pyramid + positioning-first:
Foundation: Barbara Minto, "The Pyramid Principle: Logic in Writing and Thinking"
Key insight: "Any intelligent reader can absorb only one thought at a time, and will automatically assume that any sentence that follows a previous one is intended to explain that thought further."
Application: Therefore, organize content to match how readers naturally process information - top-down, hierarchical, answer-first.
Skill Version: 1.0 Created: 2025-10-31 Used by: architect agent (outlines), author agent (optional) Key Innovation: Answer-first hierarchical structure that respects reader's cognitive load
Initialize Claude Code framework infrastructure for any project
Simplification and readability techniques. Use when writing for broad audiences or simplifying complex content. Covers active voice, short sentences, jargon elimination, and accessibility principles from the Plain Language Movement.
Narrative structure for complex topics - Situation, Complication, Question, Answer
Shared configuration patterns for project setup commands. Provides security hooks, Claude framework structure templates, and framework detection patterns used across multiple setup commands.
API authentication patterns including JWT, OAuth 2.0, API keys, and session-based auth. Covers token generation, validation, refresh strategies, security best practices, and when to use each pattern. Use when implementing API authentication, choosing auth strategy, securing endpoints, or debugging auth issues. Prevents common vulnerabilities like token theft, replay attacks, and insecure storage.
Docker image optimization patterns including multi-stage builds, layer caching, security hardening, and size reduction techniques. Use when building Docker images, optimizing container size, improving build performance, or implementing Docker security best practices. Reduces image sizes by 70-90% and build times by 50-80%.