diff --git a/uk/claude_concepts_guide.md b/uk/claude_concepts_guide.md new file mode 100644 index 0000000..fbce8e4 --- /dev/null +++ b/uk/claude_concepts_guide.md @@ -0,0 +1,3135 @@ + + + Claude How To + + +# Complete Guide to Claude Concepts + +A comprehensive reference guide covering Slash Commands, Subagents, Memory, MCP Protocol, and Agent Skills with tables, diagrams, and practical examples. + +--- + +## Table of Contents + +1. [Slash Commands](#slash-commands) +2. [Subagents](#subagents) +3. [Memory](#memory) +4. [MCP Protocol](#mcp-protocol) +5. [Agent Skills](#agent-skills) +6. [Plugins](#claude-code-plugins) +7. [Hooks](#hooks) +8. [Checkpoints and Rewind](#checkpoints-and-rewind) +9. [Advanced Features](#advanced-features) +10. [Comparison & Integration](#comparison--integration) + +--- + +## Slash Commands + +### Overview + +Slash commands are user-invoked shortcuts stored as Markdown files that Claude Code can execute. They enable teams to standardize frequently-used prompts and workflows. + +### Architecture + +```mermaid +graph TD + A["User Input: /command-name"] -->|Triggers| B["Search .claude/commands/"] + B -->|Finds| C["command-name.md"] + C -->|Loads| D["Markdown Content"] + D -->|Executes| E["Claude Processes Prompt"] + E -->|Returns| F["Result in Context"] +``` + +### File Structure + +```mermaid +graph LR + A["Project Root"] -->|contains| B[".claude/commands/"] + B -->|contains| C["optimize.md"] + B -->|contains| D["test.md"] + B -->|contains| E["docs/"] + E -->|contains| F["generate-api-docs.md"] + E -->|contains| G["generate-readme.md"] +``` + +### Command Organization Table + +| Location | Scope | Availability | Use Case | Git Tracked | +|----------|-------|--------------|----------|-------------| +| `.claude/commands/` | Project-specific | Team members | Team workflows, shared standards | ✅ Yes | +| `~/.claude/commands/` | Personal | Individual user | Personal shortcuts across projects | ❌ No | +| Subdirectories | Namespaced | Based on parent | Organize by category | ✅ Yes | + +### Features & Capabilities + +| Feature | Example | Supported | +|---------|---------|-----------| +| Shell script execution | `bash scripts/deploy.sh` | ✅ Yes | +| File references | `@path/to/file.js` | ✅ Yes | +| Bash integration | `$(git log --oneline)` | ✅ Yes | +| Arguments | `/pr --verbose` | ✅ Yes | +| MCP commands | `/mcp__github__list_prs` | ✅ Yes | + +### Practical Examples + +#### Example 1: Code Optimization Command + +**File:** `.claude/commands/optimize.md` + +```markdown +--- +name: Code Optimization +description: Analyze code for performance issues and suggest optimizations +tags: performance, analysis +--- + +# Code Optimization + +Review the provided code for the following issues in order of priority: + +1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops +2. **Memory leaks** - find unreleased resources, circular references +3. **Algorithm improvements** - suggest better algorithms or data structures +4. **Caching opportunities** - identify repeated computations +5. **Concurrency issues** - find race conditions or threading problems + +Format your response with: +- Issue severity (Critical/High/Medium/Low) +- Location in code +- Explanation +- Recommended fix with code example +``` + +**Usage:** +```bash +# User types in Claude Code +/optimize + +# Claude loads the prompt and waits for code input +``` + +#### Example 2: Pull Request Helper Command + +**File:** `.claude/commands/pr.md` + +```markdown +--- +name: Prepare Pull Request +description: Clean up code, stage changes, and prepare a pull request +tags: git, workflow +--- + +# Pull Request Preparation Checklist + +Before creating a PR, execute these steps: + +1. Run linting: `prettier --write .` +2. Run tests: `npm test` +3. Review git diff: `git diff HEAD` +4. Stage changes: `git add .` +5. Create commit message following conventional commits: + - `fix:` for bug fixes + - `feat:` for new features + - `docs:` for documentation + - `refactor:` for code restructuring + - `test:` for test additions + - `chore:` for maintenance + +6. Generate PR summary including: + - What changed + - Why it changed + - Testing performed + - Potential impacts +``` + +**Usage:** +```bash +/pr + +# Claude runs through checklist and prepares the PR +``` + +#### Example 3: Hierarchical Documentation Generator + +**File:** `.claude/commands/docs/generate-api-docs.md` + +```markdown +--- +name: Generate API Documentation +description: Create comprehensive API documentation from source code +tags: documentation, api +--- + +# API Documentation Generator + +Generate API documentation by: + +1. Scanning all files in `/src/api/` +2. Extracting function signatures and JSDoc comments +3. Organizing by endpoint/module +4. Creating markdown with examples +5. Including request/response schemas +6. Adding error documentation + +Output format: +- Markdown file in `/docs/api.md` +- Include curl examples for all endpoints +- Add TypeScript types +``` + +### Command Lifecycle Diagram + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/commands/ + FS-->>Claude: Returns optimize.md + Claude->>Claude: Loads Markdown content + Claude->>User: Displays prompt context + User->>Claude: Provides code to analyze + Claude->>CLI: (May execute scripts) + CLI-->>Claude: Results + Claude->>User: Returns analysis +``` + +### Best Practices + +| ✅ Do | ❌ Don't | +|------|---------| +| Use clear, action-oriented names | Create commands for one-time tasks | +| Document trigger words in description | Build complex logic in commands | +| Keep commands focused on single task | Create redundant commands | +| Version control project commands | Hardcode sensitive information | +| Organize in subdirectories | Create long lists of commands | +| Use simple, readable prompts | Use abbreviated or cryptic wording | + +--- + +## Subagents + +### Overview + +Subagents are specialized AI assistants with isolated context windows and customized system prompts. They enable delegated task execution while maintaining clean separation of concerns. + +### Architecture Diagram + +```mermaid +graph TB + User["👤 User"] + Main["🎯 Main Agent
(Coordinator)"] + Reviewer["🔍 Code Reviewer
Subagent"] + Tester["✅ Test Engineer
Subagent"] + Docs["📝 Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### Subagent Lifecycle + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +### Subagent Configuration Table + +| Configuration | Type | Purpose | Example | +|---------------|------|---------|---------| +| `name` | String | Agent identifier | `code-reviewer` | +| `description` | String | Purpose & trigger terms | `Comprehensive code quality analysis` | +| `tools` | List/String | Allowed capabilities | `read, grep, diff, lint_runner` | +| `system_prompt` | Markdown | Behavioral instructions | Custom guidelines | + +### Tool Access Hierarchy + +```mermaid +graph TD + A["Subagent Configuration"] -->|Option 1| B["Inherit All Tools
from Main Thread"] + A -->|Option 2| C["Specify Individual Tools"] + B -->|Includes| B1["File Operations"] + B -->|Includes| B2["Shell Commands"] + B -->|Includes| B3["MCP Tools"] + C -->|Explicit List| C1["read, grep, diff"] + C -->|Explicit List| C2["Bash(npm:*), Bash(test:*)"] +``` + +### Practical Examples + +#### Example 1: Complete Subagent Setup + +**File:** `.claude/agents/code-reviewer.md` + +```yaml +--- +name: code-reviewer +description: Comprehensive code quality and maintainability analysis +tools: read, grep, diff, lint_runner +--- + +# Code Reviewer Agent + +You are an expert code reviewer specializing in: +- Performance optimization +- Security vulnerabilities +- Code maintainability +- Testing coverage +- Design patterns + +## Review Priorities (in order) + +1. **Security Issues** - Authentication, authorization, data exposure +2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries +3. **Code Quality** - Readability, naming, documentation +4. **Test Coverage** - Missing tests, edge cases +5. **Design Patterns** - SOLID principles, architecture + +## Review Output Format + +For each issue: +- **Severity**: Critical / High / Medium / Low +- **Category**: Security / Performance / Quality / Testing / Design +- **Location**: File path and line number +- **Issue Description**: What's wrong and why +- **Suggested Fix**: Code example +- **Impact**: How this affects the system + +## Example Review + +### Issue: N+1 Query Problem +- **Severity**: High +- **Category**: Performance +- **Location**: src/user-service.ts:45 +- **Issue**: Loop executes database query in each iteration +- **Fix**: Use JOIN or batch query +``` + +**File:** `.claude/agents/test-engineer.md` + +```yaml +--- +name: test-engineer +description: Test strategy, coverage analysis, and automated testing +tools: read, write, bash, grep +--- + +# Test Engineer Agent + +You are expert at: +- Writing comprehensive test suites +- Ensuring high code coverage (>80%) +- Testing edge cases and error scenarios +- Performance benchmarking +- Integration testing + +## Testing Strategy + +1. **Unit Tests** - Individual functions/methods +2. **Integration Tests** - Component interactions +3. **End-to-End Tests** - Complete workflows +4. **Edge Cases** - Boundary conditions +5. **Error Scenarios** - Failure handling + +## Test Output Requirements + +- Use Jest for JavaScript/TypeScript +- Include setup/teardown for each test +- Mock external dependencies +- Document test purpose +- Include performance assertions when relevant + +## Coverage Requirements + +- Minimum 80% code coverage +- 100% for critical paths +- Report missing coverage areas +``` + +**File:** `.claude/agents/documentation-writer.md` + +```yaml +--- +name: documentation-writer +description: Technical documentation, API docs, and user guides +tools: read, write, grep +--- + +# Documentation Writer Agent + +You create: +- API documentation with examples +- User guides and tutorials +- Architecture documentation +- Changelog entries +- Code comment improvements + +## Documentation Standards + +1. **Clarity** - Use simple, clear language +2. **Examples** - Include practical code examples +3. **Completeness** - Cover all parameters and returns +4. **Structure** - Use consistent formatting +5. **Accuracy** - Verify against actual code + +## Documentation Sections + +### For APIs +- Description +- Parameters (with types) +- Returns (with types) +- Throws (possible errors) +- Examples (curl, JavaScript, Python) +- Related endpoints + +### For Features +- Overview +- Prerequisites +- Step-by-step instructions +- Expected outcomes +- Troubleshooting +- Related topics +``` + +#### Example 2: Subagent Delegation in Action + +```markdown +# Scenario: Building a Payment Feature + +## User Request +"Build a secure payment processing feature that integrates with Stripe" + +## Main Agent Flow + +1. **Planning Phase** + - Understands requirements + - Determines tasks needed + - Plans architecture + +2. **Delegates to Code Reviewer Subagent** + - Task: "Review the payment processing implementation for security" + - Context: Auth, API keys, token handling + - Reviews for: SQL injection, key exposure, HTTPS enforcement + +3. **Delegates to Test Engineer Subagent** + - Task: "Create comprehensive tests for payment flows" + - Context: Success scenarios, failures, edge cases + - Creates tests for: Valid payments, declined cards, network failures, webhooks + +4. **Delegates to Documentation Writer Subagent** + - Task: "Document the payment API endpoints" + - Context: Request/response schemas + - Produces: API docs with curl examples, error codes + +5. **Synthesis** + - Main agent collects all outputs + - Integrates findings + - Returns complete solution to user +``` + +#### Example 3: Tool Permission Scoping + +**Restrictive Setup - Limited to Specific Commands** + +```yaml +--- +name: secure-reviewer +description: Security-focused code review with minimal permissions +tools: read, grep +--- + +# Secure Code Reviewer + +Reviews code for security vulnerabilities only. + +This agent: +- ✅ Reads files to analyze +- ✅ Searches for patterns +- ❌ Cannot execute code +- ❌ Cannot modify files +- ❌ Cannot run tests + +This ensures the reviewer doesn't accidentally break anything. +``` + +**Extended Setup - All Tools for Implementation** + +```yaml +--- +name: implementation-agent +description: Full implementation capabilities for feature development +tools: read, write, bash, grep, edit, glob +--- + +# Implementation Agent + +Builds features from specifications. + +This agent: +- ✅ Reads specifications +- ✅ Writes new code files +- ✅ Runs build commands +- ✅ Searches codebase +- ✅ Edits existing files +- ✅ Finds files matching patterns + +Full capabilities for independent feature development. +``` + +### Subagent Context Management + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5ff + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### When to Use Subagents + +| Scenario | Use Subagent | Why | +|----------|--------------|-----| +| Complex feature with many steps | ✅ Yes | Separate concerns, prevent context pollution | +| Quick code review | ❌ No | Not necessary overhead | +| Parallel task execution | ✅ Yes | Each subagent has own context | +| Specialized expertise needed | ✅ Yes | Custom system prompts | +| Long-running analysis | ✅ Yes | Prevents main context exhaustion | +| Single task | ❌ No | Adds latency unnecessarily | + +### Agent Teams + +Agent Teams coordinate multiple agents working on related tasks. Rather than delegating to one subagent at a time, Agent Teams allow the main agent to orchestrate a group of agents that collaborate, share intermediate results, and work toward a common goal. This is useful for large-scale tasks like full-stack feature development where a frontend agent, backend agent, and testing agent work in parallel. + +--- + +## Memory + +### Overview + +Memory enables Claude to retain context across sessions and conversations. It exists in two forms: automatic synthesis in claude.ai, and filesystem-based CLAUDE.md in Claude Code. + +### Memory Architecture + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +### Memory Hierarchy in Claude Code (7 Tiers) + +Claude Code loads memory from 7 tiers, listed from highest to lowest priority: + +```mermaid +graph TD + A["1. Managed Policy
Enterprise admin policies"] --> B["2. Project Memory
./CLAUDE.md"] + B --> C["3. Project Rules
.claude/rules/*.md"] + C --> D["4. User Memory
~/.claude/CLAUDE.md"] + D --> E["5. User Rules
~/.claude/rules/*.md"] + E --> F["6. Local Memory
.claude/local/CLAUDE.md"] + F --> G["7. Auto Memory
Automatically captured preferences"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 +``` + +### Memory Locations Table + +| Tier | Location | Scope | Priority | Shared | Best For | +|------|----------|-------|----------|--------|----------| +| 1. Managed Policy | Enterprise admin | Organization | Highest | All org users | Compliance, security policies | +| 2. Project | `./CLAUDE.md` | Project | High | Team (Git) | Team standards, architecture | +| 3. Project Rules | `.claude/rules/*.md` | Project | High | Team (Git) | Modular project conventions | +| 4. User | `~/.claude/CLAUDE.md` | Personal | Medium | Individual | Personal preferences | +| 5. User Rules | `~/.claude/rules/*.md` | Personal | Medium | Individual | Personal rule modules | +| 6. Local | `.claude/local/CLAUDE.md` | Local | Low | Not shared | Machine-specific settings | +| 7. Auto Memory | Automatic | Session | Lowest | Individual | Learned preferences, patterns | + +### Auto Memory + +Auto Memory automatically captures user preferences and patterns observed during sessions. Claude learns from your interactions and remembers: + +- Coding style preferences +- Common corrections you make +- Framework and tool choices +- Communication style preferences + +Auto Memory works in the background and does not require manual configuration. + +### Memory Update Lifecycle + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +### Practical Examples + +#### Example 1: Project Memory Structure + +**File:** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +#### Example 2: Directory-Specific Memory + +**File:** `./src/api/CLAUDE.md` + +~~~~markdown +# API Module Standards + +This file overrides root CLAUDE.md for everything in /src/api/ + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +### Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +~~~~ + +#### Example 3: Personal Memory + +**File:** `~/.claude/CLAUDE.md` + +~~~~markdown +# My Development Preferences + +## About Me +- **Experience Level**: 8 years full-stack development +- **Preferred Languages**: TypeScript, Python +- **Communication Style**: Direct, with examples +- **Learning Style**: Visual diagrams with code + +## Code Preferences + +### Error Handling +I prefer explicit error handling with try-catch blocks and meaningful error messages. +Avoid generic errors. Always log errors for debugging. + +### Comments +Use comments for WHY, not WHAT. Code should be self-documenting. +Comments should explain business logic or non-obvious decisions. + +### Testing +I prefer TDD (test-driven development). +Write tests first, then implementation. +Focus on behavior, not implementation details. + +### Architecture +I prefer modular, loosely-coupled design. +Use dependency injection for testability. +Separate concerns (Controllers, Services, Repositories). + +## Debugging Preferences +- Use console.log with prefix: `[DEBUG]` +- Include context: function name, relevant variables +- Use stack traces when available +- Always include timestamps in logs + +## Communication +- Explain complex concepts with diagrams +- Show concrete examples before explaining theory +- Include before/after code snippets +- Summarize key points at the end + +## Project Organization +I organize my projects as: +``` +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## Tooling +- **IDE**: VS Code with vim keybindings +- **Terminal**: Zsh with Oh-My-Zsh +- **Format**: Prettier (100 char line length) +- **Linter**: ESLint with airbnb config +- **Test Framework**: Jest with React Testing Library +~~~~ + +#### Example 4: Memory Update During Session + +**Session Interaction:** + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +### Memory in Claude Web/Desktop + +#### Memory Synthesis Timeline + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**Example Memory Summary:** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +### Memory Features Comparison + +| Feature | Claude Web/Desktop | Claude Code (CLAUDE.md) | +|---------|-------------------|------------------------| +| Auto-synthesis | ✅ Every 24h | ❌ Manual | +| Cross-project | ✅ Shared | ❌ Project-specific | +| Team access | ✅ Shared projects | ✅ Git-tracked | +| Searchable | ✅ Built-in | ✅ Through `/memory` | +| Editable | ✅ In-chat | ✅ Direct file edit | +| Import/Export | ✅ Yes | ✅ Copy/paste | +| Persistent | ✅ 24h+ | ✅ Indefinite | + +--- + +## MCP Protocol + +### Overview + +MCP (Model Context Protocol) is a standardized way for Claude to access external tools, APIs, and real-time data sources. Unlike Memory, MCP provides live access to changing data. + +### MCP Architecture + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A +``` + +### MCP Ecosystem + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] +``` + +### MCP Setup Process + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: ✅ MCP connected! +``` + +### Available MCP Servers Table + +| MCP Server | Purpose | Common Tools | Auth | Real-time | +|------------|---------|--------------|------|-----------| +| **Filesystem** | File operations | read, write, delete | OS permissions | ✅ Yes | +| **GitHub** | Repository management | list_prs, create_issue, push | OAuth | ✅ Yes | +| **Slack** | Team communication | send_message, list_channels | Token | ✅ Yes | +| **Database** | SQL queries | query, insert, update | Credentials | ✅ Yes | +| **Google Docs** | Document access | read, write, share | OAuth | ✅ Yes | +| **Asana** | Project management | create_task, update_status | API Key | ✅ Yes | +| **Stripe** | Payment data | list_charges, create_invoice | API Key | ✅ Yes | +| **Memory** | Persistent memory | store, retrieve, delete | Local | ❌ No | + +### Practical Examples + +#### Example 1: GitHub MCP Configuration + +**File:** `.mcp.json` (project scope) or `~/.claude.json` (user scope) + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**Available GitHub MCP Tools:** + +~~~~markdown +# GitHub MCP Tools + +## Pull Request Management +- `list_prs` - List all PRs in repository +- `get_pr` - Get PR details including diff +- `create_pr` - Create new PR +- `update_pr` - Update PR description/title +- `merge_pr` - Merge PR to main branch +- `review_pr` - Add review comments + +Example request: +``` +/mcp__github__get_pr 456 + +# Returns: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +## Issue Management +- `list_issues` - List all issues +- `get_issue` - Get issue details +- `create_issue` - Create new issue +- `close_issue` - Close issue +- `add_comment` - Add comment to issue + +## Repository Information +- `get_repo_info` - Repository details +- `list_files` - File tree structure +- `get_file_content` - Read file contents +- `search_code` - Search across codebase + +## Commit Operations +- `list_commits` - Commit history +- `get_commit` - Specific commit details +- `create_commit` - Create new commit +~~~~ + +#### Example 2: Database MCP Setup + +**Configuration:** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**Example Usage:** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Using MCP database tool: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Results: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +#### Example 3: Multi-MCP Workflow + +**Scenario: Daily Report Generation** + +```markdown +# Daily Report Workflow using Multiple MCPs + +## Setup +1. GitHub MCP - fetch PR metrics +2. Database MCP - query sales data +3. Slack MCP - post report +4. Filesystem MCP - save report + +## Workflow + +### Step 1: Fetch GitHub Data +/mcp__github__list_prs completed:true last:7days + +Output: +- Total PRs: 42 +- Average merge time: 2.3 hours +- Review turnaround: 1.1 hours + +### Step 2: Query Database +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +Output: +- Sales: 247 +- Revenue: $12,450 + +### Step 3: Generate Report +Combine data into HTML report + +### Step 4: Save to Filesystem +Write report.html to /reports/ + +### Step 5: Post to Slack +Send summary to #daily-reports channel + +Final Output: +✅ Report generated and posted +📊 47 PRs merged this week +💰 $12,450 in daily sales +``` + +#### Example 4: Filesystem MCP Operations + +**Configuration:** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**Available Operations:** + +| Operation | Command | Purpose | +|-----------|---------|---------| +| List files | `ls ~/projects` | Show directory contents | +| Read file | `cat src/main.ts` | Read file contents | +| Write file | `create docs/api.md` | Create new file | +| Edit file | `edit src/app.ts` | Modify file | +| Search | `grep "async function"` | Search in files | +| Delete | `rm old-file.js` | Delete file | + +### MCP vs Memory: Decision Matrix + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style B fill:#e1f5ff + style D fill:#fff9c4 +``` + +### Request/Response Pattern + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +--- + +## Agent Skills + +### Overview + +Agent Skills are reusable, model-invoked capabilities packaged as folders containing instructions, scripts, and resources. Claude automatically detects and uses relevant skills. + +### Skill Architecture + +```mermaid +graph TB + A["Skill Directory"] + B["SKILL.md"] + C["YAML Metadata"] + D["Instructions"] + E["Scripts"] + F["Templates"] + + A --> B + B --> C + B --> D + E --> A + F --> A +``` + +### Skill Loading Process + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude + participant System as System + participant Skill as Skill + + User->>Claude: "Create Excel report" + Claude->>System: Scan available skills + System->>System: Load skill metadata + Claude->>Claude: Match user request to skills + Claude->>Skill: Load xlsx skill SKILL.md + Skill-->>Claude: Return instructions + tools + Claude->>Claude: Execute skill + Claude->>User: Generate Excel file +``` + +### Skill Types & Locations Table + +| Type | Location | Scope | Shared | Sync | Best For | +|------|----------|-------|--------|------|----------| +| Pre-built | Built-in | Global | All users | Auto | Document creation | +| Personal | `~/.claude/skills/` | Individual | No | Manual | Personal automation | +| Project | `.claude/skills/` | Team | Yes | Git | Team standards | +| Plugin | Via plugin install | Varies | Depends | Auto | Integrated features | + +### Pre-built Skills + +```mermaid +graph TB + A["Pre-built Skills"] + B["PowerPoint (pptx)"] + C["Excel (xlsx)"] + D["Word (docx)"] + E["PDF"] + + A --> B + A --> C + A --> D + A --> E + + B --> B1["Create presentations"] + B --> B2["Edit slides"] + C --> C1["Create spreadsheets"] + C --> C2["Analyze data"] + D --> D1["Create documents"] + D --> D2["Format text"] + E --> E1["Generate PDFs"] + E --> E2["Fill forms"] +``` + +### Bundled Skills + +Claude Code now includes 5 bundled skills available out of the box: + +| Skill | Command | Purpose | +|-------|---------|---------| +| **Simplify** | `/simplify` | Simplify complex code or explanations | +| **Batch** | `/batch` | Run operations across multiple files or items | +| **Debug** | `/debug` | Systematic debugging of issues with root cause analysis | +| **Loop** | `/loop` | Schedule recurring tasks on a timer | +| **Claude API** | `/claude-api` | Interact with the Anthropic API directly | + +These bundled skills are always available and do not require installation or configuration. + +### Practical Examples + +#### Example 1: Custom Code Review Skill + +**Directory Structure:** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**File:** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: Code Review Specialist +description: Comprehensive code review with security, performance, and quality analysis +version: "1.0.0" +tags: + - code-review + - quality + - security +when_to_use: When users ask to review code, analyze code quality, or evaluate pull requests +effort: high +shell: bash +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + - Sensitive data logging + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + - Concurrency issues + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Documentation + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Dependency management + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +### Findings by Category + +#### Security (if issues found) +List security vulnerabilities with examples + +#### Performance (if issues found) +List performance problems with complexity analysis + +#### Quality (if issues found) +List code quality issues with refactoring suggestions + +#### Maintainability (if issues found) +List maintainability problems with improvements +``` +## Python Script: analyze-metrics.py + +```python +#!/usr/bin/env python3 +import re +import sys + +def analyze_code_metrics(code): + """Analyze code for common metrics.""" + + # Count functions + functions = len(re.findall(r'^def\s+\w+', code, re.MULTILINE)) + + # Count classes + classes = len(re.findall(r'^class\s+\w+', code, re.MULTILINE)) + + # Average line length + lines = code.split('\n') + avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0 + + # Estimate complexity + complexity = len(re.findall(r'\b(if|elif|else|for|while|and|or)\b', code)) + + return { + 'functions': functions, + 'classes': classes, + 'avg_line_length': avg_length, + 'complexity_score': complexity + } + +if __name__ == '__main__': + with open(sys.argv[1], 'r') as f: + code = f.read() + metrics = analyze_code_metrics(code) + for key, value in metrics.items(): + print(f"{key}: {value:.2f}") +``` + +## Python Script: compare-complexity.py + +```python +#!/usr/bin/env python3 +""" +Compare cyclomatic complexity of code before and after changes. +Helps identify if refactoring actually simplifies code structure. +""" + +import re +import sys +from typing import Dict, Tuple + +class ComplexityAnalyzer: + """Analyze code complexity metrics.""" + + def __init__(self, code: str): + self.code = code + self.lines = code.split('\n') + + def calculate_cyclomatic_complexity(self) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + Count decision points: if, elif, else, for, while, except, and, or + """ + complexity = 1 # Base complexity + + # Count decision points + decision_patterns = [ + r'\bif\b', + r'\belif\b', + r'\bfor\b', + r'\bwhile\b', + r'\bexcept\b', + r'\band\b(?!$)', + r'\bor\b(?!$)' + ] + + for pattern in decision_patterns: + matches = re.findall(pattern, self.code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self) -> int: + """ + Calculate cognitive complexity - how hard is it to understand? + Based on nesting depth and control flow. + """ + cognitive = 0 + nesting_depth = 0 + + for line in self.lines: + # Track nesting depth + if re.search(r'^\s*(if|for|while|def|class|try)\b', line): + nesting_depth += 1 + cognitive += nesting_depth + elif re.search(r'^\s*(elif|else|except|finally)\b', line): + cognitive += nesting_depth + + # Reduce nesting when unindenting + if line and not line[0].isspace(): + nesting_depth = 0 + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Maintainability Index ranges from 0-100. + > 85: Excellent + > 65: Good + > 50: Fair + < 50: Poor + """ + lines = len(self.lines) + cyclomatic = self.calculate_cyclomatic_complexity() + cognitive = self.calculate_cognitive_complexity() + + # Simplified MI calculation + mi = 171 - 5.2 * (cyclomatic / lines) - 0.23 * (cognitive) - 16.2 * (lines / 1000) + + return max(0, min(100, mi)) + + def get_complexity_report(self) -> Dict: + """Generate comprehensive complexity report.""" + return { + 'cyclomatic_complexity': self.calculate_cyclomatic_complexity(), + 'cognitive_complexity': self.calculate_cognitive_complexity(), + 'maintainability_index': round(self.calculate_maintainability_index(), 2), + 'lines_of_code': len(self.lines), + 'avg_line_length': round(sum(len(l) for l in self.lines) / len(self.lines), 2) if self.lines else 0 + } + + +def compare_files(before_file: str, after_file: str) -> None: + """Compare complexity metrics between two code versions.""" + + with open(before_file, 'r') as f: + before_code = f.read() + + with open(after_file, 'r') as f: + after_code = f.read() + + before_analyzer = ComplexityAnalyzer(before_code) + after_analyzer = ComplexityAnalyzer(after_code) + + before_metrics = before_analyzer.get_complexity_report() + after_metrics = after_analyzer.get_complexity_report() + + print("=" * 60) + print("CODE COMPLEXITY COMPARISON") + print("=" * 60) + + print("\nBEFORE:") + print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {before_metrics['maintainability_index']}") + print(f" Lines of Code: {before_metrics['lines_of_code']}") + print(f" Avg Line Length: {before_metrics['avg_line_length']}") + + print("\nAFTER:") + print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {after_metrics['maintainability_index']}") + print(f" Lines of Code: {after_metrics['lines_of_code']}") + print(f" Avg Line Length: {after_metrics['avg_line_length']}") + + print("\nCHANGES:") + cyclomatic_change = after_metrics['cyclomatic_complexity'] - before_metrics['cyclomatic_complexity'] + cognitive_change = after_metrics['cognitive_complexity'] - before_metrics['cognitive_complexity'] + mi_change = after_metrics['maintainability_index'] - before_metrics['maintainability_index'] + loc_change = after_metrics['lines_of_code'] - before_metrics['lines_of_code'] + + print(f" Cyclomatic Complexity: {cyclomatic_change:+d}") + print(f" Cognitive Complexity: {cognitive_change:+d}") + print(f" Maintainability Index: {mi_change:+.2f}") + print(f" Lines of Code: {loc_change:+d}") + + print("\nASSESSMENT:") + if mi_change > 0: + print(" ✅ Code is MORE maintainable") + elif mi_change < 0: + print(" ⚠️ Code is LESS maintainable") + else: + print(" ➡️ Maintainability unchanged") + + if cyclomatic_change < 0: + print(" ✅ Complexity DECREASED") + elif cyclomatic_change > 0: + print(" ⚠️ Complexity INCREASED") + else: + print(" ➡️ Complexity unchanged") + + print("=" * 60) + + +if __name__ == '__main__': + if len(sys.argv) != 3: + print("Usage: python compare-complexity.py ") + sys.exit(1) + + compare_files(sys.argv[1], sys.argv[2]) +``` + +## Template: review-checklist.md + +```markdown +# Code Review Checklist + +## Security Checklist +- [ ] No hardcoded credentials or secrets +- [ ] Input validation on all user inputs +- [ ] SQL injection prevention (parameterized queries) +- [ ] CSRF protection on state-changing operations +- [ ] XSS prevention with proper escaping +- [ ] Authentication checks on protected endpoints +- [ ] Authorization checks on resources +- [ ] Secure password hashing (bcrypt, argon2) +- [ ] No sensitive data in logs +- [ ] HTTPS enforced + +## Performance Checklist +- [ ] No N+1 queries +- [ ] Appropriate use of indexes +- [ ] Caching implemented where beneficial +- [ ] No blocking operations on main thread +- [ ] Async/await used correctly +- [ ] Large datasets paginated +- [ ] Database connections pooled +- [ ] Regular expressions optimized +- [ ] No unnecessary object creation +- [ ] Memory leaks prevented + +## Quality Checklist +- [ ] Functions < 50 lines +- [ ] Clear variable naming +- [ ] No duplicate code +- [ ] Proper error handling +- [ ] Comments explain WHY, not WHAT +- [ ] No console.logs in production +- [ ] Type checking (TypeScript/JSDoc) +- [ ] SOLID principles followed +- [ ] Design patterns applied correctly +- [ ] Self-documenting code + +## Testing Checklist +- [ ] Unit tests written +- [ ] Edge cases covered +- [ ] Error scenarios tested +- [ ] Integration tests present +- [ ] Coverage > 80% +- [ ] No flaky tests +- [ ] Mock external dependencies +- [ ] Clear test names +``` + +## Template: finding-template.md + +~~~~markdown +# Code Review Finding Template + +Use this template when documenting each issue found during code review. + +--- + +## Issue: [TITLE] + +### Severity +- [ ] Critical (blocks deployment) +- [ ] High (should fix before merge) +- [ ] Medium (should fix soon) +- [ ] Low (nice to have) + +### Category +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### Location +**File:** `src/components/UserCard.tsx` + +**Lines:** 45-52 + +**Function/Method:** `renderUserDetails()` + +### Issue Description + +**What:** Describe what the issue is. + +**Why it matters:** Explain the impact and why this needs to be fixed. + +**Current behavior:** Show the problematic code or behavior. + +**Expected behavior:** Describe what should happen instead. + +### Code Example + +#### Current (Problematic) + +```typescript +// Shows the N+1 query problem +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // Query per user! + renderUserPosts(posts); +}); +``` + +#### Suggested Fix + +```typescript +// Optimized with JOIN query +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### Impact Analysis + +| Aspect | Impact | Severity | +|--------|--------|----------| +| Performance | 100+ queries for 20 users | High | +| User Experience | Slow page load | High | +| Scalability | Breaks at scale | Critical | +| Maintainability | Hard to debug | Medium | + +### Related Issues + +- Similar issue in `AdminUserList.tsx` line 120 +- Related PR: #456 +- Related issue: #789 + +### Additional Resources + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### Reviewer Notes + +- This is a common pattern in this codebase +- Consider adding this to the code style guide +- Might be worth creating a helper function + +### Author Response (for feedback) + +*To be filled by the code author:* + +- [ ] Fix implemented in commit: `abc123` +- [ ] Fix status: Complete / In Progress / Needs Discussion +- [ ] Questions or concerns: (describe) + +--- + +## Finding Statistics (for Reviewer) + +When reviewing multiple findings, track: + +- **Total Issues Found:** X +- **Critical:** X +- **High:** X +- **Medium:** X +- **Low:** X + +**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion + +**Overall Code Quality:** 1-5 stars +~~~~ + +## Usage Example + +~~~~markdown +User: Review this React component code + +Claude: I'll conduct a comprehensive code review using my Code Review Skill. + +[Loads SKILL.md] +[Analyzes code against checklist] +[Runs Python metrics script] +[Applies templates] + +## Code Review Results + +### Summary +Quality Score: 3.5/5 +Key Findings: 7 items +Priority Areas: Performance optimization, error handling + +### Critical Issues: 1 + +**Issue**: N+1 Query Problem +**Location**: UserComponent.tsx, lines 45-52 +**Impact**: Renders 100+ database queries for list of 20 users +**Severity**: High +**Fix**: +```javascript +// Before: N+1 queries +const users = fetchUsers(); +users.forEach(user => fetchUserPosts(user.id)); // 20+ queries + +// After: Single query with JOIN +const users = fetchUsersWithPosts(); // 1 query +``` + +### Performance Findings +- Missing pagination on large lists +- Recommendation: Use React.memo() for items +- Database query: Could be optimized with index + +### Quality Findings +- Function in line 20 is 127 lines (max: 50) +- Missing error boundary +- Props should have TypeScript types +~~~~ + +#### Example 2: Brand Voice Skill + +**Directory Structure:** + +``` +.claude/skills/brand-voice/ +├── SKILL.md +├── brand-guidelines.md +├── tone-examples.md +└── templates/ + ├── email-template.txt + ├── social-post-template.txt + └── blog-post-template.md +``` + +**File:** `.claude/skills/brand-voice/SKILL.md` + +```yaml +--- +name: Brand Voice Consistency +description: Ensure all communication matches brand voice and tone guidelines +tags: + - brand + - writing + - consistency +when_to_use: When creating marketing copy, customer communications, or public-facing content +--- + +# Brand Voice Skill + +## Overview +This skill ensures all communications maintain consistent brand voice, tone, and messaging. + +## Brand Identity + +### Mission +Help teams automate their development workflows with AI + +### Values +- **Simplicity**: Make complex things simple +- **Reliability**: Rock-solid execution +- **Empowerment**: Enable human creativity + +### Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon, explain technical concepts simply +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs and pain points + +## Writing Guidelines + +### Do's ✅ +- Use "you" when addressing readers +- Use active voice: "Claude generates reports" not "Reports are generated by Claude" +- Start with value proposition +- Use concrete examples +- Keep sentences under 20 words +- Use lists for clarity +- Include calls-to-action + +### Don'ts ❌ +- Don't use corporate jargon +- Don't patronize or oversimplify +- Don't use "we believe" or "we think" +- Don't use ALL CAPS except for emphasis +- Don't create walls of text +- Don't assume technical knowledge + +## Vocabulary + +### ✅ Preferred Terms +- Claude (not "the Claude AI") +- Code generation (not "auto-coding") +- Agent (not "bot") +- Streamline (not "revolutionize") +- Integrate (not "synergize") + +### ❌ Avoid Terms +- "Cutting-edge" (overused) +- "Game-changer" (vague) +- "Leverage" (corporate-speak) +- "Utilize" (use "use") +- "Paradigm shift" (unclear) +``` +## Examples + +### ✅ Good Example +"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week." + +Why it works: Clear value, specific benefits, action-oriented + +### ❌ Bad Example +"Claude leverages cutting-edge AI to provide comprehensive software development solutions." + +Why it doesn't work: Vague, corporate jargon, no specific value + +## Template: Email + +``` +Subject: [Clear, benefit-driven subject] + +Hi [Name], + +[Opening: What's the value for them] + +[Body: How it works / What they'll get] + +[Specific example or benefit] + +[Call to action: Clear next step] + +Best regards, +[Name] +``` + +## Template: Social Media + +``` +[Hook: Grab attention in first line] +[2-3 lines: Value or interesting fact] +[Call to action: Link, question, or engagement] +[Emoji: 1-2 max for visual interest] +``` + +## File: tone-examples.md +``` +Exciting announcement: +"Save 8 hours per week on code reviews. Claude reviews your PRs automatically." + +Empathetic support: +"We know deployments can be stressful. Claude handles testing so you don't have to worry." + +Confident product feature: +"Claude doesn't just suggest code. It understands your architecture and maintains consistency." + +Educational blog post: +"Let's explore how agents improve code review workflows. Here's what we learned..." +``` + +#### Example 3: Documentation Generator Skill + +**File:** `.claude/skills/doc-generator/SKILL.md` + +~~~~yaml +--- +name: API Documentation Generator +description: Generate comprehensive, accurate API documentation from source code +version: "1.0.0" +tags: + - documentation + - api + - automation +when_to_use: When creating or updating API documentation +--- + +# API Documentation Generator Skill + +## Generates + +- OpenAPI/Swagger specifications +- API endpoint documentation +- SDK usage examples +- Integration guides +- Error code references +- Authentication guides + +## Documentation Structure + +### For Each Endpoint + +```markdown +## GET /api/v1/users/:id + +### Description +Brief explanation of what this endpoint does + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | User ID | + +### Response + +**200 Success** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Not Found** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### Examples + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` + +## Python Script: generate-docs.py + +```python +#!/usr/bin/env python3 +import ast +import json +from typing import Dict, List + +class APIDocExtractor(ast.NodeVisitor): + """Extract API documentation from Python source code.""" + + def __init__(self): + self.endpoints = [] + + def visit_FunctionDef(self, node): + """Extract function documentation.""" + if node.name.startswith('get_') or node.name.startswith('post_'): + doc = ast.get_docstring(node) + endpoint = { + 'name': node.name, + 'docstring': doc, + 'params': [arg.arg for arg in node.args.args], + 'returns': self._extract_return_type(node) + } + self.endpoints.append(endpoint) + self.generic_visit(node) + + def _extract_return_type(self, node): + """Extract return type from function annotation.""" + if node.returns: + return ast.unparse(node.returns) + return "Any" + +def generate_markdown_docs(endpoints: List[Dict]) -> str: + """Generate markdown documentation from endpoints.""" + docs = "# API Documentation\n\n" + + for endpoint in endpoints: + docs += f"## {endpoint['name']}\n\n" + docs += f"{endpoint['docstring']}\n\n" + docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n" + docs += f"**Returns**: {endpoint['returns']}\n\n" + docs += "---\n\n" + + return docs + +if __name__ == '__main__': + import sys + with open(sys.argv[1], 'r') as f: + tree = ast.parse(f.read()) + + extractor = APIDocExtractor() + extractor.visit(tree) + + markdown = generate_markdown_docs(extractor.endpoints) + print(markdown) +~~~~ +### Skill Discovery & Invocation + +```mermaid +graph TD + A["User Request"] --> B["Claude Analyzes"] + B -->|Scans| C["Available Skills"] + C -->|Metadata check| D["Skill Description Match?"] + D -->|Yes| E["Load SKILL.md"] + D -->|No| F["Try next skill"] + F -->|More skills?| D + F -->|No more| G["Use general knowledge"] + E --> H["Extract Instructions"] + H --> I["Execute Skill"] + I --> J["Return Results"] +``` + +### Skill vs Other Features + +```mermaid +graph TB + A["Extending Claude"] + B["Slash Commands"] + C["Subagents"] + D["Memory"] + E["MCP"] + F["Skills"] + + A --> B + A --> C + A --> D + A --> E + A --> F + + B -->|User-invoked| G["Quick shortcuts"] + C -->|Auto-delegated| H["Isolated contexts"] + D -->|Persistent| I["Cross-session context"] + E -->|Real-time| J["External data access"] + F -->|Auto-invoked| K["Autonomous execution"] +``` + +--- + +## Claude Code Plugins + +### Overview + +Claude Code Plugins are bundled collections of customizations (slash commands, subagents, MCP servers, and hooks) that install with a single command. They represent the highest-level extension mechanism—combining multiple features into cohesive, shareable packages. + +### Architecture + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +### Plugin Loading Process + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +### Plugin Types & Distribution + +| Type | Scope | Shared | Authority | Examples | +|------|-------|--------|-----------|----------| +| Official | Global | All users | Anthropic | PR Review, Security Guidance | +| Community | Public | All users | Community | DevOps, Data Science | +| Organization | Internal | Team members | Company | Internal standards, tools | +| Personal | Individual | Single user | Developer | Custom workflows | + +### Plugin Definition Structure + +```yaml +--- +name: plugin-name +version: "1.0.0" +description: "What this plugin does" +author: "Your Name" +license: MIT + +# Plugin metadata +tags: + - category + - use-case + +# Requirements +requires: + - claude-code: ">=1.0.0" + +# Components bundled +components: + - type: commands + path: commands/ + - type: agents + path: agents/ + - type: mcp + path: mcp/ + - type: hooks + path: hooks/ + +# Configuration +config: + auto_load: true + enabled_by_default: true +--- +``` + +### Plugin Structure + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json +├── commands/ +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ +│ └── hooks.json +├── .mcp.json +├── .lsp.json +├── settings.json +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### Practical Examples + +#### Example 1: PR Review Plugin + +**File:** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "license": "MIT" +} +``` + +**File:** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**File:** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**Installation:** + +```bash +/plugin install pr-review + +# Result: +# ✅ 3 slash commands installed +# ✅ 3 subagents configured +# ✅ 2 MCP servers connected +# ✅ 4 hooks registered +# ✅ Ready to use! +``` + +#### Example 2: DevOps Plugin + +**Components:** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +#### Example 3: Documentation Plugin + +**Bundled Components:** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +### Plugin Marketplace + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
Anthropic"] + C["Community
Marketplace"] + D["Enterprise
Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] +``` + +### Plugin Installation & Lifecycle + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +### Plugin Features Comparison + +| Feature | Slash Command | Skill | Subagent | Plugin | +|---------|---------------|-------|----------|--------| +| **Installation** | Manual copy | Manual copy | Manual config | One command | +| **Setup Time** | 5 minutes | 10 minutes | 15 minutes | 2 minutes | +| **Bundling** | Single file | Single file | Single file | Multiple | +| **Versioning** | Manual | Manual | Manual | Automatic | +| **Team Sharing** | Copy file | Copy file | Copy file | Install ID | +| **Updates** | Manual | Manual | Manual | Auto-available | +| **Dependencies** | None | None | None | May include | +| **Marketplace** | No | No | No | Yes | +| **Distribution** | Repository | Repository | Repository | Marketplace | + +### Plugin Use Cases + +| Use Case | Recommendation | Why | +|----------|-----------------|-----| +| **Team Onboarding** | ✅ Use Plugin | Instant setup, all configurations | +| **Framework Setup** | ✅ Use Plugin | Bundles framework-specific commands | +| **Enterprise Standards** | ✅ Use Plugin | Central distribution, version control | +| **Quick Task Automation** | ❌ Use Command | Overkill complexity | +| **Single Domain Expertise** | ❌ Use Skill | Too heavy, use skill instead | +| **Specialized Analysis** | ❌ Use Subagent | Create manually or use skill | +| **Live Data Access** | ❌ Use MCP | Standalone, don't bundle | + +### When to Create a Plugin + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### Publishing a Plugin + +**Steps to publish:** + +1. Create plugin structure with all components +2. Write `.claude-plugin/plugin.json` manifest +3. Create `README.md` with documentation +4. Test locally with `/plugin install ./my-plugin` +5. Submit to plugin marketplace +6. Get reviewed and approved +7. Published on marketplace +8. Users can install with one command + +**Example submission:** + +~~~~markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +~~~~ + +### Plugin vs Manual Configuration + +**Manual Setup (2+ hours):** +- Install slash commands one by one +- Create subagents individually +- Configure MCPs separately +- Set up hooks manually +- Document everything +- Share with team (hope they configure correctly) + +**With Plugin (2 minutes):** +```bash +/plugin install pr-review +# ✅ Everything installed and configured +# ✅ Ready to use immediately +# ✅ Team can reproduce exact setup +``` + +--- + +## Comparison & Integration + +### Feature Comparison Matrix + +| Feature | Invocation | Persistence | Scope | Use Case | +|---------|-----------|------------|-------|----------| +| **Slash Commands** | Manual (`/cmd`) | Session only | Single command | Quick shortcuts | +| **Subagents** | Auto-delegated | Isolated context | Specialized task | Task distribution | +| **Memory** | Auto-loaded | Cross-session | User/team context | Long-term learning | +| **MCP Protocol** | Auto-queried | Real-time external | Live data access | Dynamic information | +| **Skills** | Auto-invoked | Filesystem-based | Reusable expertise | Automated workflows | + +### Interaction Timeline + +```mermaid +graph LR + A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"] + B -->|Discover| C["Available Skills"] + C -->|Register| D["Slash Commands"] + D -->|Connect| E["MCP Servers"] + E -->|Ready| F["User Interaction"] + + F -->|Type /cmd| G["Slash Command"] + F -->|Request| H["Skill Auto-Invoke"] + F -->|Query| I["MCP Data"] + F -->|Complex task| J["Delegate to Subagent"] + + G -->|Uses| B + H -->|Uses| B + I -->|Uses| B + J -->|Uses| B +``` + +### Practical Integration Example: Customer Support Automation + +#### Architecture + +```mermaid +graph TB + User["Customer Email"] -->|Receives| Router["Support Router"] + + Router -->|Analyze| Memory["Memory
Customer history"] + Router -->|Lookup| MCP1["MCP: Customer DB
Previous tickets"] + Router -->|Check| MCP2["MCP: Slack
Team status"] + + Router -->|Route Complex| Sub1["Subagent: Tech Support
Context: Technical issues"] + Router -->|Route Simple| Sub2["Subagent: Billing
Context: Payment issues"] + Router -->|Route Urgent| Sub3["Subagent: Escalation
Context: Priority handling"] + + Sub1 -->|Format| Skill1["Skill: Response Generator
Brand voice maintained"] + Sub2 -->|Format| Skill2["Skill: Response Generator"] + Sub3 -->|Format| Skill3["Skill: Response Generator"] + + Skill1 -->|Generate| Output["Formatted Response"] + Skill2 -->|Generate| Output + Skill3 -->|Generate| Output + + Output -->|Post| MCP3["MCP: Slack
Notify team"] + Output -->|Send| Reply["Customer Reply"] +``` + +#### Request Flow + +```markdown +## Customer Support Request Flow + +### 1. Incoming Email +"I'm getting error 500 when trying to upload files. This is blocking my workflow!" + +### 2. Memory Lookup +- Loads CLAUDE.md with support standards +- Checks customer history: VIP customer, 3rd incident this month + +### 3. MCP Queries +- GitHub MCP: List open issues (finds related bug report) +- Database MCP: Check system status (no outages reported) +- Slack MCP: Check if engineering is aware + +### 4. Skill Detection & Loading +- Request matches "Technical Support" skill +- Loads support response template from Skill + +### 5. Subagent Delegation +- Routes to Tech Support Subagent +- Provides context: customer history, error details, known issues +- Subagent has full access to: read, bash, grep tools + +### 6. Subagent Processing +Tech Support Subagent: +- Searches codebase for 500 error in file upload +- Finds recent change in commit 8f4a2c +- Creates workaround documentation + +### 7. Skill Execution +Response Generator Skill: +- Uses Brand Voice guidelines +- Formats response with empathy +- Includes workaround steps +- Links to related documentation + +### 8. MCP Output +- Posts update to #support Slack channel +- Tags engineering team +- Updates ticket in Jira MCP + +### 9. Response +Customer receives: +- Empathetic acknowledgment +- Explanation of cause +- Immediate workaround +- Timeline for permanent fix +- Link to related issues +``` + +### Complete Feature Orchestration + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Memory as Memory
CLAUDE.md + participant MCP as MCP Servers + participant Skills as Skills + participant SubAgent as Subagents + + User->>Claude: Request: "Build auth system" + Claude->>Memory: Load project standards + Memory-->>Claude: Auth standards, team practices + Claude->>MCP: Query GitHub for similar implementations + MCP-->>Claude: Code examples, best practices + Claude->>Skills: Detect matching Skills + Skills-->>Claude: Security Review Skill + Testing Skill + Claude->>SubAgent: Delegate implementation + SubAgent->>SubAgent: Build feature + Claude->>Skills: Apply Security Review Skill + Skills-->>Claude: Security checklist results + Claude->>SubAgent: Delegate testing + SubAgent-->>Claude: Test results + Claude->>User: Complete system delivered +``` + +### When to Use Each Feature + +```mermaid +graph TD + A["New Task"] --> B{Type of Task?} + + B -->|Repeated workflow| C["Slash Command"] + B -->|Need real-time data| D["MCP Protocol"] + B -->|Remember for next time| E["Memory"] + B -->|Specialized subtask| F["Subagent"] + B -->|Domain-specific work| G["Skill"] + + C --> C1["✅ Team shortcut"] + D --> D1["✅ Live API access"] + E --> E1["✅ Persistent context"] + F --> F1["✅ Parallel execution"] + G --> G1["✅ Auto-invoked expertise"] +``` + +### Selection Decision Tree + +```mermaid +graph TD + Start["Need to extend Claude?"] + + Start -->|Quick repeated task| A{"Manual or Auto?"} + A -->|Manual| B["Slash Command"] + A -->|Auto| C["Skill"] + + Start -->|Need external data| D{"Real-time?"} + D -->|Yes| E["MCP Protocol"] + D -->|No/Cross-session| F["Memory"] + + Start -->|Complex project| G{"Multiple roles?"} + G -->|Yes| H["Subagents"] + G -->|No| I["Skills + Memory"] + + Start -->|Long-term context| J["Memory"] + Start -->|Team workflow| K["Slash Command +
Memory"] + Start -->|Full automation| L["Skills +
Subagents +
MCP"] +``` + +--- + +## Summary Table + +| Aspect | Slash Commands | Subagents | Memory | MCP | Skills | Plugins | +|--------|---|---|---|---|---|---| +| **Setup Difficulty** | Easy | Medium | Easy | Medium | Medium | Easy | +| **Learning Curve** | Low | Medium | Low | Medium | Medium | Low | +| **Team Benefit** | High | High | Medium | High | High | Very High | +| **Automation Level** | Low | High | Medium | High | High | Very High | +| **Context Management** | Single-session | Isolated | Persistent | Real-time | Persistent | All features | +| **Maintenance Burden** | Low | Medium | Low | Medium | Medium | Low | +| **Scalability** | Good | Excellent | Good | Excellent | Excellent | Excellent | +| **Shareability** | Fair | Fair | Good | Good | Good | Excellent | +| **Versioning** | Manual | Manual | Manual | Manual | Manual | Automatic | +| **Installation** | Manual copy | Manual config | N/A | Manual config | Manual copy | One command | + +--- + +## Quick Start Guide + +### Week 1: Start Simple +- Create 2-3 slash commands for common tasks +- Enable Memory in Settings +- Document team standards in CLAUDE.md + +### Week 2: Add Real-time Access +- Set up 1 MCP (GitHub or Database) +- Use `/mcp` to configure +- Query live data in your workflows + +### Week 3: Distribute Work +- Create first Subagent for specific role +- Use `/agents` command +- Test delegation with simple task + +### Week 4: Automate Everything +- Create first Skill for repeated automation +- Use Skill marketplace or build custom +- Combine all features for full workflow + +### Ongoing +- Review and update Memory monthly +- Add new Skills as patterns emerge +- Optimize MCP queries +- Refine Subagent prompts + +--- + +## Hooks + +### Overview + +Hooks are event-driven shell commands that execute automatically in response to Claude Code events. They enable automation, validation, and custom workflows without manual intervention. + +### Hook Events + +Claude Code supports **25 hook events** across four hook types (command, http, prompt, agent): + +| Hook Event | Trigger | Use Cases | +|------------|---------|-----------| +| **SessionStart** | Session begins/resumes/clear/compact | Environment setup, initialization | +| **InstructionsLoaded** | CLAUDE.md or rules file loaded | Validation, transformation, augmentation | +| **UserPromptSubmit** | User submits prompt | Input validation, prompt filtering | +| **PreToolUse** | Before any tool runs | Validation, approval gates, logging | +| **PermissionRequest** | Permission dialog shown | Auto-approve/deny flows | +| **PostToolUse** | After tool succeeds | Auto-formatting, notifications, cleanup | +| **PostToolUseFailure** | Tool execution fails | Error handling, logging | +| **Notification** | Notification sent | Alerting, external integrations | +| **SubagentStart** | Subagent spawned | Context injection, initialization | +| **SubagentStop** | Subagent finishes | Result validation, logging | +| **Stop** | Claude finishes responding | Summary generation, cleanup tasks | +| **StopFailure** | API error ends turn | Error recovery, logging | +| **TeammateIdle** | Agent team teammate idle | Work distribution, coordination | +| **TaskCompleted** | Task marked complete | Post-task processing | +| **TaskCreated** | Task created via TaskCreate | Task tracking, logging | +| **ConfigChange** | Config file changes | Validation, propagation | +| **CwdChanged** | Working directory changes | Directory-specific setup | +| **FileChanged** | Watched file changes | File monitoring, rebuild triggers | +| **PreCompact** | Before context compaction | State preservation | +| **PostCompact** | After compaction completes | Post-compact actions | +| **WorktreeCreate** | Worktree being created | Environment setup, dependency install | +| **WorktreeRemove** | Worktree being removed | Cleanup, resource deallocation | +| **Elicitation** | MCP server requests user input | Input validation | +| **ElicitationResult** | User responds to elicitation | Response processing | +| **SessionEnd** | Session terminates | Cleanup, final logging | + +### Common Hooks + +Hooks are configured in `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level): + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "prettier --write $CLAUDE_FILE_PATH" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Edit", + "hooks": [ + { + "type": "command", + "command": "eslint $CLAUDE_FILE_PATH" + } + ] + } + ] + } +} +``` + +### Hook Environment Variables + +- `$CLAUDE_FILE_PATH` - Path to file being edited/written +- `$CLAUDE_TOOL_NAME` - Name of tool being used +- `$CLAUDE_SESSION_ID` - Current session identifier +- `$CLAUDE_PROJECT_DIR` - Project directory path + +### Best Practices + +✅ **Do:** +- Keep hooks fast (< 1 second) +- Use hooks for validation and automation +- Handle errors gracefully +- Use absolute paths + +❌ **Don't:** +- Make hooks interactive +- Use hooks for long-running tasks +- Hardcode credentials + +**See**: [06-hooks/](06-hooks/) for detailed examples + +--- + +## Checkpoints and Rewind + +### Overview + +Checkpoints allow you to save conversation state and rewind to previous points, enabling safe experimentation and exploration of multiple approaches. + +### Key Concepts + +| Concept | Description | +|---------|-------------| +| **Checkpoint** | Snapshot of conversation state including messages, files, and context | +| **Rewind** | Return to a previous checkpoint, discarding subsequent changes | +| **Branch Point** | Checkpoint from which multiple approaches are explored | + +### Accessing Checkpoints + +Checkpoints are created automatically with every user prompt. To rewind: + +```bash +# Press Esc twice to open the checkpoint browser +Esc + Esc + +# Or use the /rewind command +/rewind +``` + +When you select a checkpoint, you choose from five options: +1. **Restore code and conversation** -- Revert both to that point +2. **Restore conversation** -- Rewind messages, keep current code +3. **Restore code** -- Revert files, keep conversation +4. **Summarize from here** -- Compress conversation into a summary +5. **Never mind** -- Cancel + +### Use Cases + +| Scenario | Workflow | +|----------|----------| +| **Exploring Approaches** | Save → Try A → Save → Rewind → Try B → Compare | +| **Safe Refactoring** | Save → Refactor → Test → If fail: Rewind | +| **A/B Testing** | Save → Design A → Save → Rewind → Design B → Compare | +| **Mistake Recovery** | Notice issue → Rewind to last good state | + +### Configuration + +```json +{ + "autoCheckpoint": true +} +``` + +**See**: [08-checkpoints/](08-checkpoints/) for detailed examples + +--- + +## Advanced Features + +### Planning Mode + +Create detailed implementation plans before coding. + +**Activation:** +```bash +/plan Implement user authentication system +``` + +**Benefits:** +- Clear roadmap with time estimates +- Risk assessment +- Systematic task breakdown +- Opportunity for review and modification + +### Extended Thinking + +Deep reasoning for complex problems. + +**Activation:** +- Toggle with `Alt+T` (or `Option+T` on macOS) during a session +- Set `MAX_THINKING_TOKENS` environment variable for programmatic control + +```bash +# Enable extended thinking via environment variable +export MAX_THINKING_TOKENS=50000 +claude -p "Should we use microservices or monolith?" +``` + +**Benefits:** +- Thorough analysis of trade-offs +- Better architectural decisions +- Consideration of edge cases +- Systematic evaluation + +### Background Tasks + +Run long operations without blocking the conversation. + +**Usage:** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Show all tasks +/task status bg-1234 # Check progress +/task show bg-1234 # View output +/task cancel bg-1234 # Cancel task +``` + +### Permission Modes + +Control what Claude can do. + +| Mode | Description | Use Case | +|------|-------------|----------| +| **default** | Standard permissions with prompts for sensitive actions | General development | +| **acceptEdits** | Automatically accept file edits without confirmation | Trusted editing workflows | +| **plan** | Analysis and planning only, no file modifications | Code review, architecture planning | +| **auto** | Automatically approve safe actions, prompt only for risky ones | Balanced autonomy with safety | +| **dontAsk** | Execute all actions without confirmation prompts | Experienced users, automation | +| **bypassPermissions** | Full unrestricted access, no safety checks | CI/CD pipelines, trusted scripts | + +**Usage:** +```bash +claude --permission-mode plan # Read-only analysis +claude --permission-mode acceptEdits # Auto-accept edits +claude --permission-mode auto # Auto-approve safe actions +claude --permission-mode dontAsk # No confirmation prompts +``` + +### Headless Mode (Print Mode) + +Run Claude Code without interactive input for automation and CI/CD using the `-p` (print) flag. + +**Usage:** +```bash +# Run specific task +claude -p "Run all tests" + +# Pipe input for analysis +cat error.log | claude -p "explain this error" + +# CI/CD integration (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR changes and report issues" + +# JSON output for scripting +claude -p --output-format json "list all functions in src/" +``` + +### Scheduled Tasks + +Run tasks on a repeating schedule using the `/loop` command. + +**Usage:** +```bash +/loop every 30m "Run tests and report failures" +/loop every 2h "Check for dependency updates" +/loop every 1d "Generate daily summary of code changes" +``` + +Scheduled tasks run in the background and report results when complete. They are useful for continuous monitoring, periodic checks, and automated maintenance workflows. + +### Chrome Integration + +Claude Code can integrate with the Chrome browser for web automation tasks. This enables capabilities like navigating web pages, filling forms, taking screenshots, and extracting data from websites directly within your development workflow. + +### Session Management + +Manage multiple work sessions. + +**Commands:** +```bash +/resume # Resume a previous conversation +/rename "Feature" # Name the current session +/fork # Fork into a new session +claude -c # Continue most recent conversation +claude -r "Feature" # Resume session by name/ID +``` + +### Interactive Features + +**Keyboard Shortcuts:** +- `Ctrl + R` - Search command history +- `Tab` - Autocomplete +- `↑ / ↓` - Command history +- `Ctrl + L` - Clear screen + +**Multi-line Input:** +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +### Configuration + +Complete configuration example: + +```json +{ + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "permissions": { + "mode": "default" + } +} +``` + +**See**: [09-advanced-features/](09-advanced-features/) for comprehensive guide + +--- + +## Resources + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [Anthropic Documentation](https://docs.anthropic.com) +- [MCP GitHub Servers](https://github.com/modelcontextprotocol/servers) +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) + +--- + +*Last updated: April 2026* +*For Claude Haiku 4.5, Sonnet 4.6, and Opus 4.6* +*Now includes: Hooks, Checkpoints, Planning Mode, Extended Thinking, Background Tasks, Permission Modes (6 modes), Headless Mode, Session Management, Auto Memory, Agent Teams, Scheduled Tasks, Chrome Integration, Channels, Voice Dictation, and Bundled Skills* + +--- +**Last Updated**: April 9, 2026 +**Claude Code Version**: 2.1.97 diff --git a/uk/docs/ROADMAP-20260401.md b/uk/docs/ROADMAP-20260401.md new file mode 100644 index 0000000..e333c56 --- /dev/null +++ b/uk/docs/ROADMAP-20260401.md @@ -0,0 +1,153 @@ +# Roadmap: claude-howto 2026–2027 + +> April 2026 – March 2027 · Dual-Layer Knowledge Base | Full plan: `TASKS-20260401.md` + +--- + +## Vision + +Transform claude-howto from a static tutorial repo into a **living, dual-audience knowledge system**: + +- **For humans** — interactive, scenario-based learning with progressive difficulty, decision trees, and named patterns that experts bookmark +- **For AI agents** — structured metadata index that agents query before performing Claude Code tasks, making this repo infrastructure, not just content + +No competitor targets AI agents as a primary audience. This is the moat. + +--- + +## The 7 Pillars + +| # | Pillar | What it delivers | +|---|--------|-----------------| +| P1 | Fun Layer | Scenario intros + "Try It Now" blocks in every module | +| P2 | AI Agent Index | Generated `agent-manifest.json` + `AGENT-INDEX.md` + lookup skill | +| P3a | Expert Reference (in-module) | Decision trees + named patterns per module | +| P3b | Expert Reference (cross-module) | `RECIPES.md` — compound multi-feature workflows | +| P4 | Newcomer Onboarding | `quickstart.sh` + `QUICKSTART.md` + difficulty badges | +| P5 | Community Showcase | `COMMUNITY-PROJECTS.md` — curated user projects | +| P6 | Content Quality | Expand weakest modules; project `CLAUDE.md` | +| P7 | Living Curriculum | `WHATS-NEW.md` + version badges + weekly staleness CI action | + +--- + +## Timeline at a Glance + +``` +Apr 2026 May–Jun 2026 Jul–Aug 2026 Sep 2026 Oct–Nov 2026 Dec 2026–Mar 2027 + | | | | | | + [M1] [M2] [M3] [M4] [M5] [M6] +Infrastructure 6/10 modules 10/10 Agent layer Version audit Self-sustaining ++ hooks/checks complete complete + recipes complete system +``` + +--- + +## Milestones + +### M1 — Infrastructure Live · End of April 2026 + +**What ships:** +- `scripts/quickstart.sh` — one-command setup for new users (idempotent) +- `QUICKSTART.md` — First 15 Minutes visual guide +- Difficulty badges + "What you'll build" previews on all 10 modules +- `WHATS-NEW.md` + version badges on all modules +- `.github/workflows/staleness-check.yml` — weekly Monday issue if module unverified 30+ days +- Root `CLAUDE.md` — project's own configuration as a best-practice example +- `scripts/build-agent-index.py` — generator that reads all 10 modules → outputs `agent-manifest.json` + `AGENT-INDEX.md` +- **06-hooks** — full deep pass: 5 complete hook scripts, decision tree, Try It Now, patterns +- **08-checkpoints** — full deep pass: 311 → 800+ lines, 3 workflow templates, decision tree, patterns + +**Why start here:** Infrastructure benefits every future phase. Hooks and checkpoints are the weakest modules and most likely to lose new visitors. + +--- + +### M2 — 6/10 Modules Complete · End of June 2026 + +**What ships (one deep pass per module):** +- **01-slash-commands** — scenario intro, decision tree, Try It Now, named patterns +- **02-memory** — scenario intro, decision tree, Try It Now, named patterns +- **03-skills** — scenario intro, decision tree, Try It Now, named patterns +- **10-cli** — scenario intro, decision tree, Try It Now, named patterns +- CI step: validate `agent-manifest.json` schema on every push + +Each module pass = run the generator to confirm valid manifest output. + +--- + +### M3 — All 10 Modules Complete · End of August 2026 + +**What ships:** +- **04-subagents** — full deep pass (incl. "The Multi-Agent Review Pattern") +- **05-mcp** — full deep pass +- **07-plugins** — full deep pass +- **09-advanced-features** — full deep pass + +Every module now has: scenario intro, 2+ Try It Now blocks, Mermaid decision tree, 2+ named patterns. + +--- + +### M4 — Agent Layer Live · End of September 2026 + +**What ships:** +- Final `agent-manifest.json` covering 100% of modules (generated from completed content) +- `AGENT-INDEX.md` linked from `README.md` +- `skills/claude-howto-lookup/SKILL.md` — lightweight agent skill that queries the manifest +- `RECIPES.md` — 5+ compound workflows (schema: name, modules-used, problem, solution, expected outcome) +- `COMMUNITY-PROJECTS.md` — static curated list with PR-based submission format + +**Why September:** The agent index is only meaningful once all 10 modules are content-complete. + +--- + +### M5 — Version Audit Complete · End of November 2026 + +**What ships:** +- Full version audit: all 10 modules verified against current CC version +- Updated `cc_version_verified` frontmatter + version badges everywhere +- `RECIPES.md` expanded to 8+ recipes based on observed community patterns +- Pinned GitHub Discussion: "Share your Claude Code workflows" — signal collection for agent usage + +--- + +### M6 — Self-Sustaining System · End of March 2027 + +**What ships / runs continuously:** +- `/docs-sync-claude-code` skill runs after every CC release → `WHATS-NEW.md` updated +- Agent manifest CI regression: 100% module coverage enforced +- `RECIPES.md` at 10+ recipes +- `COMMUNITY-PROJECTS.md` growing organically +- Agent usage signal evaluated → if validated, promote the lookup skill (marketing, asm registry) + +--- + +## Deliverables Summary + +| Deliverable | Type | Phase | +|-------------|------|-------| +| `scripts/quickstart.sh` | Script | P1 | +| `QUICKSTART.md` | Doc | P1 | +| Root `CLAUDE.md` | Config | P1 | +| `WHATS-NEW.md` | Doc | P1 | +| `.github/workflows/staleness-check.yml` | CI | P1 | +| `scripts/build-agent-index.py` | Script | P1 | +| 10 module deep passes (scenario + Try It Now + decision tree + patterns) | Content | P1–P3 | +| `agent-manifest.json` (generated) | Data | P4 | +| `AGENT-INDEX.md` (generated) | Doc | P4 | +| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 | +| `RECIPES.md` (5 → 8 → 10+ recipes) | Doc | P4–P6 | +| `COMMUNITY-PROJECTS.md` | Doc | P4 | + +--- + +## What Is NOT in Scope + +Deferred to `TODOS.md` — do not let these creep in: + +- Skill marketplace or installable registry +- Custom website or dashboard +- Completion tracking (cc-progress) +- Community tutorial CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure +- Community voting on projects diff --git a/uk/docs/TASKS-20260401.md b/uk/docs/TASKS-20260401.md new file mode 100644 index 0000000..fdad321 --- /dev/null +++ b/uk/docs/TASKS-20260401.md @@ -0,0 +1,291 @@ +# Tasks: Dual-Layer Knowledge Base — claude-howto + +> Created: 2026-04-01 + +--- + +## Milestones + +| # | Milestone | Target | Description | +|---|-----------|--------|-------------| +| M1 | Infrastructure Live | End of April 2026 | quickstart.sh, CLAUDE.md, staleness action, agent index generator live; 2 weakest modules upgraded | +| M2 | 6/10 Modules Complete | End of June 2026 | Slash commands, memory, skills, CLI modules fully upgraded; generator producing valid manifest | +| M3 | All 10 Modules Complete | End of August 2026 | Every module has scenario intro, Try It Now blocks, decision tree, named patterns | +| M4 | Agent Layer Live | End of September 2026 | agent-manifest.json + AGENT-INDEX.md generated; lookup skill in repo; RECIPES.md + COMMUNITY-PROJECTS.md live | +| M5 | Version Audit Complete | End of November 2026 | All 10 modules verified against current CC version; RECIPES.md at 8+ recipes | +| M6 | Self-Sustaining System | End of March 2027 | Agent manifest covers 100% modules (CI-validated); RECIPES.md at 10+; community page growing organically | + +--- + +## Phase 1 — Infrastructure & Weak Modules (April 2026) + +**Target milestone: M1** + +### Pillar 4: Newcomer Onboarding + +- [ ] **T-001** — Write `scripts/quickstart.sh` + - Detects `~/.claude/` directory (creates with user confirmation if missing) + - Copies first slash command + CLAUDE.md + skill to user's setup + - Appends agent-discovery line to CLAUDE.md linking to AGENT-INDEX.md + - Idempotent: skips existing files with a warning, never overwrites + - Prints next steps on completion + +- [ ] **T-002** — Create `QUICKSTART.md` (First 15 Minutes visual guide) + - Annotated terminal steps as code blocks (avoid PNG screenshots where possible; prefer ASCII or Mermaid) + - Document which commands produce each visual so they can be re-captured + +- [ ] **T-003** — Add difficulty badges to all 10 module READMEs + - Format: `> 🟢 **Beginner** | ⏱ 30 minutes` at top of each module README + - Add "What you'll build" bullet preview below the badge + +### Pillar 7: Living Curriculum + +- [ ] **T-004** — Create `WHATS-NEW.md` + - Format: `## CC vX.X — DATE` with bullet items per feature change + - Add at least one entry for current CC version + +- [ ] **T-005** — Add version badges to all 10 module READMEs + - Format: `> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD` + - Add `cc_version_verified` to each module's frontmatter + +- [ ] **T-006** — Create `.github/workflows/staleness-check.yml` + - Schedule: weekly Monday 09:00 UTC + - Reads each module's `last_verified` date from frontmatter (use `yq` or 10-line Python script) + - Creates a GitHub Issue for any module not verified in 30+ days + - Skips if open issue with same title already exists + +### Pillar 6: Content Quality (CLAUDE.md) + +- [ ] **T-007** — Create root `CLAUDE.md` for the project + - Demonstrates best practices as the project's own configuration + - Documents contributing conventions, module structure, and maintenance workflow + +### Pillar 2: AI Agent Index (Generator) + +- [ ] **T-008** — Write `scripts/build-agent-index.py` + - Reads all 10 module README files + - Extracts: headings (→ topics), code blocks (→ examples with language tags), tables (→ reference data) + - Outputs `agent-manifest.json` with schema defined in CEO plan + - Outputs `AGENT-INDEX.md` (human-readable summary) + - Validates references point to actual files + +### Module 08-checkpoints: Full Deep Pass (311 → 800+ lines) + +- [ ] **T-009** — Rewrite module intro with real-world scenario + - Example: "Your refactor just broke 3 things. Here's how checkpoints save you..." + +- [ ] **T-010** — Add checkpoint strategy decision tree (Mermaid flowchart) + - "I want to do X" → follow arrows → land on checkpoint pattern + +- [ ] **T-011** — Add 3 workflow templates + - Safe refactoring workflow + - A/B testing with checkpoints + - Disaster recovery workflow + +- [ ] **T-012** — Add integration with planning mode section + +- [ ] **T-013** — Add Mermaid diagram for checkpoint lifecycle + +- [ ] **T-014** — Add 2+ "Try It Now" blocks with verifiable commands + - Each: context sentence, command to run, expected output description + +- [ ] **T-015** — Add "Patterns & Recipes" section with 2+ named patterns + - Each pattern: problem, solution code, when to use, when NOT to use + +### Module 06-hooks: Full Deep Pass + +- [ ] **T-016** — Rewrite module intro with real-world scenario + - Example: "Your CI caught a lint error after 20 minutes. Hooks catch it in 2 seconds..." + +- [ ] **T-017** — Add hooks decision tree (Mermaid flowchart) + - "I want to trigger X when Y happens" → follow arrows → land on hook type + +- [ ] **T-018** — Add 5 complete hook examples with full scripts (~80 lines each) + 1. Auto-format on write (prettier/black) + 2. Security scan on commit (trufflehog/bandit) + 3. Test runner on file change + 4. Notification on session end + 5. Prompt validation (block dangerous patterns) + +- [ ] **T-019** — Add 2+ "Try It Now" blocks with verifiable commands + +- [ ] **T-020** — Add "Patterns & Recipes" section with 2+ named patterns + +**M1 Checkpoint: infrastructure live, 2 weakest modules fully upgraded** + +--- + +## Phase 2 — Deep Pass: Strong Modules Batch 1 (May–June 2026) + +**Target milestone: M2** + +### Module 01-slash-commands: Full Deep Pass + +- [ ] **T-021** — Rewrite intro with scenario ("Your teammate just pushed 47 files...") +- [ ] **T-022** — Add decision tree (Mermaid) +- [ ] **T-023** — Add 2+ "Try It Now" blocks +- [ ] **T-024** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 02-memory: Full Deep Pass + +- [ ] **T-025** — Rewrite intro with real-world scenario +- [ ] **T-026** — Add decision tree (Mermaid) +- [ ] **T-027** — Add 2+ "Try It Now" blocks +- [ ] **T-028** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 03-skills: Full Deep Pass + +- [ ] **T-029** — Rewrite intro with real-world scenario +- [ ] **T-030** — Add decision tree (Mermaid) +- [ ] **T-031** — Add 2+ "Try It Now" blocks +- [ ] **T-032** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 10-cli: Full Deep Pass + +- [ ] **T-033** — Rewrite intro with real-world scenario +- [ ] **T-034** — Add decision tree (Mermaid) +- [ ] **T-035** — Add 2+ "Try It Now" blocks +- [ ] **T-036** — Add "Patterns & Recipes" section with 2+ named patterns + +### Generator Validation + +- [ ] **T-037** — Run `scripts/build-agent-index.py` after each module upgrade; confirm valid manifest output +- [ ] **T-038** — Add CI step: validate agent-manifest.json schema on every push + +**M2 Checkpoint: 6/10 modules complete, generator producing valid manifest** + +--- + +## Phase 3 — Deep Pass: Strong Modules Batch 2 (July–August 2026) + +**Target milestone: M3** + +### Module 04-subagents: Full Deep Pass + +- [ ] **T-039** — Rewrite intro with real-world scenario +- [ ] **T-040** — Add decision tree (Mermaid) +- [ ] **T-041** — Add 2+ "Try It Now" blocks +- [ ] **T-042** — Add "Patterns & Recipes" section (e.g., "The Multi-Agent Review Pattern") + +### Module 05-mcp: Full Deep Pass + +- [ ] **T-043** — Rewrite intro with real-world scenario +- [ ] **T-044** — Add decision tree (Mermaid) +- [ ] **T-045** — Add 2+ "Try It Now" blocks +- [ ] **T-046** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 07-plugins: Full Deep Pass + +- [ ] **T-047** — Rewrite intro with real-world scenario +- [ ] **T-048** — Add decision tree (Mermaid) +- [ ] **T-049** — Add 2+ "Try It Now" blocks +- [ ] **T-050** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 09-advanced-features: Full Deep Pass + +- [ ] **T-051** — Rewrite intro with real-world scenario +- [ ] **T-052** — Add decision tree (Mermaid) +- [ ] **T-053** — Add 2+ "Try It Now" blocks +- [ ] **T-054** — Add "Patterns & Recipes" section with 2+ named patterns + +**M3 Checkpoint: all 10 modules complete and consistent** + +--- + +## Phase 4 — Agent Layer & Cross-Module (September 2026) + +**Target milestone: M4** + +### Pillar 2: Finalize AI Agent Index + +- [ ] **T-055** — Run `scripts/build-agent-index.py` against all 10 completed modules + - Produce final `agent-manifest.json` with 100% module coverage + - Produce `AGENT-INDEX.md` and link from README.md + +- [ ] **T-056** — Create `skills/claude-howto-lookup/SKILL.md` + - Reads `agent-manifest.json` to find relevant modules + - Uses `Read` to load the section + - Installation: `cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/` + +- [ ] **T-057** — Mention lookup skill in quickstart.sh and QUICKSTART.md as optional feature + +### Pillar 3b: Cross-Module RECIPES.md + +- [ ] **T-058** — Create `RECIPES.md` with 5+ compound workflows + - Schema per recipe: name, modules-used, problem, solution code block, expected outcome + - Example: skill + hook + subagent = automated review pipeline + - Ensure HTML anchors on all major headings for deep-linking + +### Pillar 5: Community Showcase + +- [ ] **T-059** — Create `COMMUNITY-PROJECTS.md` + - Static Markdown page with submission format: name, description, link, features used + - Template entry included + - PR-based submission instructions + +**M4 Checkpoint: agent index live, recipes live, community page live** + +--- + +## Phase 5 — Version Audit & Recipe Expansion (October–November 2026) + +**Target milestone: M5** + +- [ ] **T-060** — Run full version audit: verify all 10 modules against current CC version + - Update `cc_version_verified` frontmatter in each module + - Update version badges + +- [ ] **T-061** — Expand `RECIPES.md` to 8+ recipes based on observed community patterns + +- [ ] **T-062** — Iterate agent manifest schema if new patterns emerge from completed modules + +- [ ] **T-063** — Open pinned GitHub Discussion: "Share your Claude Code workflows" + - Collect signal on real agent usage to inform future recipe expansion + +**M5 Checkpoint: all modules verified current, recipes growing** + +--- + +## Phase 6 — Compound & Sustain (December 2026 – March 2027) + +**Target milestone: M6** + +- [ ] **T-064** — Run `/docs-sync-claude-code` skill after every CC release; update `WHATS-NEW.md` + +- [ ] **T-065** — Ensure agent manifest covers 100% of modules (CI regression test) + +- [ ] **T-066** — Grow `RECIPES.md` to 10+ recipes + +- [ ] **T-067** — Monitor `COMMUNITY-PROJECTS.md` for organic growth; curate new entries + +- [ ] **T-068** — Evaluate agent usage signal from GitHub Discussions; if validated, invest in promoting the lookup skill (marketing, asm registry) + +**M6 Checkpoint: the system is self-sustaining** + +--- + +## Deferred (TODOS.md) + +These items are out of scope for this plan. Record here to avoid scope creep: + +- Skill marketplace / installable registry +- Custom website or dashboard +- Completion tracking infrastructure (cc-progress) +- Community tutorial template with CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure upgrades +- Community voting/review mechanism for COMMUNITY-PROJECTS.md + +--- + +## Task Summary by Phase + +| Phase | Tasks | Period | Modules Touched | +|-------|-------|--------|-----------------| +| 1 — Infrastructure & Weak Modules | T-001 to T-020 | April 2026 | 06-hooks, 08-checkpoints + infra | +| 2 — Batch 1 Deep Pass | T-021 to T-038 | May–June 2026 | 01, 02, 03, 10 | +| 3 — Batch 2 Deep Pass | T-039 to T-054 | July–August 2026 | 04, 05, 07, 09 | +| 4 — Agent Layer & Cross-Module | T-055 to T-059 | September 2026 | All (manifest) + new files | +| 5 — Version Audit & Recipes | T-060 to T-063 | October–November 2026 | All (audit) | +| 6 — Sustain | T-064 to T-068 | December 2026–March 2027 | Ongoing | diff --git a/uk/prompts/remotion-video.md b/uk/prompts/remotion-video.md new file mode 100644 index 0000000..700023d --- /dev/null +++ b/uk/prompts/remotion-video.md @@ -0,0 +1,350 @@ +You are an expert Motion Designer and Senior React Engineer specializing in **Remotion**. Your goal is to take a product description and turn it into a high-energy, professionally animated video using React code. + +**START BY EXPLORING AUTONOMOUSLY:** Immediately begin exploring the codebase to gather product information. Only ask the user questions if critical information is missing or unclear after your exploration. + +Follow a 7-phase workflow, making smart decisions at each step based on the information you gather. + +--- + +# 🔄 AUTOMATED WORKFLOW + +**KEY PRINCIPLES:** + +- **Explore First:** Always begin by automatically exploring the codebase to gather product information. Do NOT start with questions about the product. +- **Ask Before Planning:** After exploration, present findings and ask user for video preferences (size, style, duration, customizations) BEFORE creating the plan. +- **Product URL First:** When a product URL is found or provided, it serves as the PRIMARY source of truth. Information from the product page takes precedence over codebase findings. +- **Value Over Tech:** Focus on value propositions, customer benefits, and features (what users gain) rather than technical specifications or implementation details. +- **Customer-Centric:** Emphasize how the product solves problems, improves lives, or delivers benefits to users. +- **Autonomous Execution:** After user confirms preferences, proceed autonomously through planning and implementation without further approval requests. + +## 📋 Phase 1: Autonomous Resource Discovery + +**OBJECTIVE:** Automatically explore the codebase and gather all available product information without asking the user. + +**ACTIONS:** + +1. **Automatically explore the codebase first:** + - Search for `README.md` for product description and value proposition + - Check `package.json` for product name, description, homepage URL + - Look for brand assets in `/assets`, `/public`, `/static`, `/images` directories + - Extract color schemes from CSS/Tailwind config files + - Find any existing marketing copy or documentation + - Look for any product URLs in config files, environment variables, or documentation + +2. **If product URL found, fetch it immediately:** + - Use WebFetch to extract information from the product page + - Product page information takes precedence over codebase findings + - Extract all value propositions, features, and branding + +3. **Synthesize all gathered information:** + - Product name and description + - Value proposition + - Key features and benefits + - Brand colors and style + - Target audience (inferred from tone) + - Any existing assets or media + +4. **Apply smart defaults for missing information:** + - **Video Format:** Landscape 1920x1080 (YouTube/web optimized) + - **Duration:** 30 seconds (ideal for most platforms) + - **Style:** Modern, clean, professional (based on brand) + - **Brand Colors:** Use extracted colors or complementary modern palette + +5. **Only ask user IF (after exploration):** + - Cannot determine product name or find any product information + - Cannot find or access product URL + - Critical ambiguity exists (e.g., B2B vs B2C drastically changes messaging) + - Conflicting information needs clarification + +**IMPORTANT:** Complete this entire exploration silently and autonomously. Do NOT ask "What I need to get started" or list requirements. Only interrupt the user if truly necessary. + +**OUTPUT:** Proceed immediately to Phase 2 with all gathered information. + +--- + +## 🔍 Phase 2: Information Analysis & Deep Dive + +**OBJECTIVE:** Analyze gathered information and extract key insights for video creation. + +**ACTIONS:** + +1. **Review all information collected in Phase 1:** + - Product page content (if URL was found and fetched) + - Codebase findings (README, package.json, assets, etc.) + - Any brand guidelines or marketing materials + +2. **Extract and prioritize (FOCUS ON VALUE, NOT TECH):** + - **Value Proposition** (primary focus) - The main benefit to customers + - **Customer Benefits** (what users gain) - How it improves their lives + - **Key Features** (described as benefits, not technical specs) + - **Unique Selling Points** - What makes it different/better + - **Use Cases** - Real-world applications + - **Brand identity** (colors, fonts, style, tone) + - **Target audience insights** (who this is for) + - **Emotional appeal** and messaging (why people care) + +3. **Silently fill gaps with intelligent inferences:** + - If value prop is not explicit, infer from features and target audience + - If target audience is unclear, infer from product type and messaging tone + - If brand colors are missing, create a complementary modern palette + - Avoid technical implementation details unless user-facing + +4. **Only ask for clarification IF:** + - Multiple conflicting value propositions exist + - Cannot determine if product is B2B or B2C (drastically affects messaging) + - Genuinely ambiguous target audience + +**OUTPUT:** Clear understanding of product value, benefits, and brand for video creation. + +--- + +## ✅ Phase 3: Present Findings & Gather User Preferences + +**OBJECTIVE:** Share what you discovered and get user input on video preferences before planning. + +**ACTIONS:** + +1. **Present a summary of discovered information:** + + ```text + 📊 DISCOVERED INFORMATION + + Product: [Name] + Value Proposition: [Main benefit to customers] + Key Features: [2-3 main benefits] + Brand Colors: [Extracted or suggested colors] + Target Audience: [Who this is for] + ``` + +2. **Ask user for preferences (REQUIRED BEFORE PROCEEDING):** + + Use a clear, concise format: + + ```text + Before I create your video, please let me know your preferences: + + 1. **Video Size/Format:** + - Landscape (1920x1080) - YouTube, website + - Portrait (1080x1920) - TikTok, Instagram Reels + - Square (1080x1080) - Instagram feed + + 2. **Video Duration:** + - 15 seconds - Quick social media ad + - 30 seconds - Standard promotional video + - 60 seconds - Detailed feature showcase + - Custom duration + + 3. **Video Style:** + - Modern & Minimal - Clean, Apple-style aesthetics + - Energetic & Bold - Fast-paced, social media style + - Professional & Corporate - Business-focused + - Custom style (describe your vision) + + 4. **Anything else to highlight or customize?** + (Specific features, messaging, colors, etc.) + ``` + +3. **Wait for user response** before proceeding to Phase 4. + +4. **Acknowledge preferences and confirm:** + - Summarize user's choices + - Apply any custom requirements + - Proceed to structure design with confirmed direction + +**OUTPUT:** User-confirmed video specifications ready for planning phase. + +--- + +## 📐 Phase 4: Structure Design (Post-Confirmation) + +**OBJECTIVE:** Create a compelling video structure using the 3-act format based on user preferences. + +**ACTIONS:** + +1. **Design video structure with user's confirmed preferences:** + + ```text + 🎬 VIDEO STRUCTURE + + Act 1: The Hook (0-5 seconds) + - [Attention-grabbing visual concept] + - [Bold animation entrance] + - [Compelling headline/question] + + Act 2: Value Demonstration (middle section) + - [Show key benefits in action] + - [Visual storytelling of customer value] + - [2-3 feature highlights as benefits] + + Act 3: Call to Action (final section) + - [Clear CTA with brand reinforcement] + - [Memorable closing visual] + - [Smooth exit animation] + ``` + +2. **Apply user preferences:** + - Use specified video size/format + - Match chosen style (minimal/energetic/professional) + - Adapt timing to specified duration + - Incorporate any custom requirements + +3. **Make creative decisions based on:** + - Product value proposition (what makes it compelling) + - Target audience (what resonates with them) + - User's style preferences + - Brand personality (visual and tonal consistency) + +4. **Present the structure briefly** then automatically proceed to Phase 5. + +**OUTPUT:** Complete video structure ready for implementation planning. + +--- + +## 🛠️ Phase 5: Technical Architecture + +**OBJECTIVE:** Design implementation architecture and proceed directly to building. + +**ACTIONS:** + +1. **Silently design** the component architecture: + - Utility functions (easing, animation helpers, color utilities) + - Reusable components (AnimatedTitle, FeatureHighlight, etc.) + - Scene components (Hook, Demo, CTA scenes) + - Main composition structure (Video.tsx, Root.tsx) + +2. **Plan technical details:** + - Animation timing and easing curves + - Color palette implementation + - Typography hierarchy + - Icon and asset strategy + - Sequence timing breakdown + +3. **Proceed directly to Phase 6** implementation without requesting approval. + +**OUTPUT:** Internal technical blueprint ready for immediate implementation. + +--- + +## 💻 Phase 6: Implementation + +**OBJECTIVE:** Build the complete Remotion video project autonomously. + +**CONSTRAINTS & TECH STACK:** + +1. **Framework:** Remotion (React) +2. **Styling:** Tailwind CSS (via `className` or standard style objects) +3. **Animation:** Use `spring`, `interpolate`, and `useCurrentFrame` for smooth motion +4. **Code Style:** Modular components. Do not dump everything in `Root.tsx` +5. **Best Practices:** + - Nothing should be static. Everything must have an entrance (opacity/scale/slide) and exit + - Use Lucide-React for icons if needed + - Use standard fonts but style them heavily (bold, tracking-tight) + - Do not use external images unless they are placeholders (e.g., `https://placehold.co/600x400`) or user-provided assets + +**ACTIONS:** + +1. **Build complete project structure** in this order: + - Utility functions (easing, animation helpers, color utilities) + - Reusable components (AnimatedTitle, FeatureHighlight, transitions) + - Scene components (HookScene, DemoScene, CTAScene) + - Main composition (Video.tsx with sequencing) + - Root configuration (Root.tsx with proper registration) + +2. **Work silently and efficiently:** + - Create all files without narrating every step + - Make design decisions based on gathered information + - Use professional animation principles + - Ensure smooth transitions between scenes + +3. **Automatically proceed to Phase 7** when implementation is complete. + +**OUTPUT:** Complete, production-ready Remotion project code. + +--- + +## 🎥 Phase 7: Delivery & Next Steps + +**OBJECTIVE:** Provide rendering instructions and mark project complete. + +**ACTIONS:** + +1. **Provide rendering instructions:** + + ```bash + # Preview the video in browser + npm run dev + + # Render the final video + npm run build + npx remotion render Video out/video.mp4 + + # For specific codec/settings + npx remotion render Video out/video.mp4 --codec h264 + ``` + +2. **Deliver summary:** + - Brief description of what was created + - Key features of the video + - Video specifications (duration, format, dimensions) + - Any notable design decisions + +3. **User can request changes if needed:** + - Timing adjustments + - Animation modifications + - Content updates + - Style tweaks + +**OUTPUT:** Complete Remotion project with clear rendering instructions, ready to use. + +--- + +# 🎯 QUALITY STANDARDS + +Throughout all phases, maintain these standards: + +**Visual Quality:** +- Professional-grade animations (smooth, purposeful, on-brand) +- Consistent spacing and alignment +- Readable typography with proper contrast +- Cohesive color usage + +**Technical Quality:** +- Clean, modular code architecture +- Performance-optimized (smooth 30fps playback) +- Proper use of Remotion APIs (spring, interpolate, Sequence) +- Type-safe (if using TypeScript) + +**Creative Quality:** +- Clear narrative structure +- Attention-grabbing opening +- Strong call-to-action +- Memorable visual moments + +--- + +# 🚀 Getting Started + +I'll create a professional Remotion video project for your product. Here's my workflow: + +## Phase 1-2: Autonomous Exploration (I do this automatically) + +1. Explore your codebase for product details, brand assets, and colors +2. Fetch and analyze product page (if URL found) +3. Extract value propositions and key benefits + +## Phase 3: Your Input (I'll ask you) + +1. Present what I discovered +2. Ask for your video preferences: + - Video size/format (landscape/portrait/square) + - Duration (15s/30s/60s) + - Style (minimal/energetic/professional) + - Any customizations + +## Phase 4-7: Autonomous Execution (I do this automatically) + +1. Design video structure based on your preferences +2. Build complete Remotion project with professional animations +3. Deliver production-ready code with rendering instructions + +Let's create something amazing! diff --git a/uk/resources/DESIGN-SYSTEM.md b/uk/resources/DESIGN-SYSTEM.md new file mode 100644 index 0000000..1b5e1f0 --- /dev/null +++ b/uk/resources/DESIGN-SYSTEM.md @@ -0,0 +1,121 @@ +# Claude How To — Дизайн-система + +## Візуальна ідентичність + +### Концепція дизайну іконки: Компас з кодовою дужкою + +Іконка Claude How To використовує **компас з кодовою дужкою `>`** для представлення направленої навігації кодом: + +``` + N (green) + ▲ + │ +W ───>─── E Compass = Guidance/Direction + │ > Bracket = Code/Terminal/CLI + ▼ + S (black) +``` + +Це створює: +- **Візуальна ясність**: Одразу комунікує "гайд з навігації кодом" +- **Символічне значення**: Компас = пошук шляху; `>` = код/термінал +- **Масштабованість**: Працює при будь-якому розмірі від 16px до 512px +- **Відповідність бренду**: Відповідає естетиці інструменту розробника з мінімальною палітрою + +--- + +## Кольорова система + +### Палітра + +| Колір | Hex | RGB | Використання | +|-------|-----|-----|-------------| +| Чорний (основний) | `#000000` | 0, 0, 0 | Основні обведення, текст, південна стрілка | +| Білий (фон) | `#FFFFFF` | 255, 255, 255 | Світлі фони | +| Сірий (вторинний) | `#6B7280` | 107, 114, 128 | Малі позначки, вторинний текст | +| Яскраво-зелений (акцент) | `#22C55E` | 34, 197, 94 | Північна стрілка, центральна точка, акцентні лінії | +| Майже чорний (темний фон) | `#0A0A0A` | 10, 10, 10 | Фони dark mode | + +### Коефіцієнти контрасту (WCAG) + +- Чорний на білому: **21:1** AAA +- Сірий на білому: **4.6:1** AA +- Зелений на білому: **3.2:1** (тільки декоративний, не для тексту) +- Білий на темному: **19.5:1** AAA + +### Правило акцентного кольору + +**Яскраво-зелений (#22C55E) зарезервований тільки для виділень:** +- Північна стрілка компасу +- Центральна точка +- Акцентні підкреслення/рамки +- Ніколи як фон +- Ніколи для основного тексту + +--- + +## Типографіка + +### Шрифт логотипу +- **Сімейство**: Inter, SF Pro Display, -apple-system, Segoe UI, sans-serif +- **"Claude"**: 42px, weight 700 (bold), Чорний +- **"How-To"**: 32px, weight 500 (medium), Сірий (#6B7280) +- **Підзаголовок**: 10px, weight 500, Сірий, letter-spacing 1.5px, uppercase + +--- + +## Деталі іконки + +### Специфікації компасу + +``` +Element | Stroke/Fill | Color +--------------------|----------------|------------------ +Outer ring | 3px stroke | Black / White (dark mode) +North tick | 2.5px stroke | Black / White (dark mode) +Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode) +Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode) +North needle | filled polygon | #22C55E (always green) +South needle | filled polygon | Black / White (dark mode) +> bracket | 3px stroke | Black / White (dark mode) +Center dot | filled circle | #22C55E (always green) +``` + +### Прогресія розмірів + +``` +16px → Кільце + стрілки + шеврон (мінімально) +32px → Додаються кардинальні позначки +64px → Додаються інтеркардинальні позначки +128px → Повна деталізація, всі елементи чіткі +256px → Максимальна деталізація, товсті обведення +``` + +--- + +## Настанови з розмірів + +### Розміри логотипу +- **Мінімум**: 200px ширина (для веб) +- **Рекомендовано**: 520px (нативний розмір) +- **Максимум**: Необмежено (векторний формат) +- **Пропорції**: ~4.3:1 (ширина:висота) + +### Розміри іконки +- **Мінімум**: 16px (фавікон) +- **Рекомендовано**: 64-256px (додатки, аватари) +- **Максимум**: Необмежено (векторний формат) +- **Пропорції**: 1:1 (квадрат) + +--- + +## Доступність + +- Усі тексти відповідають WCAG AA (мінімум 4.5:1) +- Зелений акцент — декоративний, не інформаційний +- Без залежності від червоно-зеленого розрізнення + +--- + +**Останнє оновлення**: Лютий 2026 +**Версія дизайн-системи**: 3.0 diff --git a/uk/resources/QUICK-START.md b/uk/resources/QUICK-START.md new file mode 100644 index 0000000..a7c446e --- /dev/null +++ b/uk/resources/QUICK-START.md @@ -0,0 +1,89 @@ +# Швидкий старт — Брендові ресурси + +## Копіювання ресурсів у ваш проєкт + +```bash +# Copy all resources to your web project +cp -r resources/ /path/to/your/website/ + +# Or just the favicons for web +cp resources/favicons/* /path/to/your/website/public/ +``` + +## Додавання в HTML (копіювання та вставка) + +```html + + + + + + +``` + +## Використання в Markdown/документації + +```markdown +# Claude How To + +![Claude How To Logo](resources/logos/claude-howto-logo.svg) + +![Icon](resources/icons/claude-howto-icon.svg) +``` + +## Рекомендовані розміри + +| Призначення | Розмір | Файл | +|-------------|--------|------| +| Заголовок сайту | 520×120 | `logos/claude-howto-logo.svg` | +| Іконка додатку | 256×256 | `icons/claude-howto-icon.svg` | +| Вкладка браузера | 32×32 | `favicons/favicon-32.svg` | +| Домашній екран мобільного | 128×128 | `favicons/favicon-128.svg` | +| Десктопний додаток | 256×256 | `favicons/favicon-256.svg` | +| Малий аватар | 64×64 | `favicons/favicon-64.svg` | + +## Значення кольорів + +```css +/* Use these in your CSS */ +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## Значення дизайну іконки + +**Компас з кодовою дужкою**: +- Кільце компасу = Навігація, структурований навчальний шлях +- Зелена північна стрілка = Напрямок, прогрес, керівництво +- Чорна південна стрілка = Основа, міцний фундамент +- Дужка `>` = Промпт терміналу, код, контекст CLI +- Позначки = Точність, структуровані кроки + +Це символізує "пошук шляху через код з чітким керівництвом". + +## Що і де використовувати + +### Сайт +- **Заголовок**: Логотип (`logos/claude-howto-logo.svg`) +- **Фавікон**: 32px (`favicons/favicon-32.svg`) +- **Соціальний превʼю**: Іконка (`icons/claude-howto-icon.svg`) + +### GitHub +- **Бейдж README**: Іконка 64-128px +- **Аватар репозиторію**: Іконка + +### Соціальні мережі +- **Аватар**: Іконка 256×256px +- **Банер**: Логотип 520×120px +- **Мініатюра**: Іконка 256×256px + +### Документація +- **Заголовки розділів**: Логотип або іконка (масштабовані) +- **Іконки навігації**: Фавікон 32-64px + +--- + +Див. [README.md](README.md) для повної документації. diff --git a/uk/resources/README.md b/uk/resources/README.md new file mode 100644 index 0000000..e54ed45 --- /dev/null +++ b/uk/resources/README.md @@ -0,0 +1,154 @@ + + + Claude How To + + +# Claude How To — Брендові ресурси + +Повна колекція логотипів, іконок та фавіконів для проєкту Claude How To. Усі ресурси використовують дизайн V3.0: компас з символом кодової дужки (`>`), що представляє направлену навігацію кодом — з палітрою Чорний/Білий/Сірий та акцентом Яскраво-зелений (#22C55E). + +## Структура каталогів + +``` +resources/ +├── logos/ +│ ├── claude-howto-logo.svg # Основний логотип - Light mode (520×120px) +│ └── claude-howto-logo-dark.svg # Основний логотип - Dark mode (520×120px) +├── icons/ +│ ├── claude-howto-icon.svg # Іконка додатку - Light mode (256×256px) +│ └── claude-howto-icon-dark.svg # Іконка додатку - Dark mode (256×256px) +└── favicons/ + ├── favicon-16.svg # Фавікон - 16×16px + ├── favicon-32.svg # Фавікон - 32×32px (основний) + ├── favicon-64.svg # Фавікон - 64×64px + ├── favicon-128.svg # Фавікон - 128×128px + └── favicon-256.svg # Фавікон - 256×256px +``` + +Додаткові ресурси в `assets/logo/`: +``` +assets/logo/ +├── logo-full.svg # Знак + текст (горизонтально) +├── logo-mark.svg # Тільки символ компасу (120×120px) +├── logo-wordmark.svg # Тільки текст +├── logo-icon.svg # Іконка додатку (512×512, округлена) +├── favicon.svg # 16×16 оптимізований +├── logo-white.svg # Біла версія для темних фонів +└── logo-black.svg # Чорна монохромна версія +``` + +## Огляд ресурсів + +### Концепція дизайну (V3.0) + +**Компас з кодовою дужкою** — навігація зустрічає код: +- **Кільце компасу** = Навігація, пошук шляху +- **Північна стрілка (зелена)** = Напрямок, прогрес на навчальному шляху +- **Південна стрілка (чорна)** = Основа, міцний фундамент +- **Дужка `>`** = Промпт терміналу, код, контекст CLI +- **Позначки** = Точність, структуроване навчання + +### Логотипи + +**Файли**: +- `logos/claude-howto-logo.svg` (Light mode) +- `logos/claude-howto-logo-dark.svg` (Dark mode) + +**Специфікації**: +- **Розмір**: 520×120 px +- **Призначення**: Основний логотип заголовку/брендингу з текстом +- **Використання**: Заголовки сайтів, бейджі README, маркетингові матеріали, друковані матеріали +- **Формат**: SVG (повністю масштабований) +- **Режими**: Light (білий фон) та Dark (фон #0A0A0A) + +### Іконки + +**Файли**: +- `icons/claude-howto-icon.svg` (Light mode) +- `icons/claude-howto-icon-dark.svg` (Dark mode) + +**Специфікації**: +- **Розмір**: 256×256 px +- **Призначення**: Іконка додатку, аватари, мініатюри +- **Формат**: SVG (повністю масштабований) + +### Фавікони + +Оптимізовані версії різних розмірів для веб-використання: + +| Файл | Розмір | DPI | Використання | +|------|--------|-----|-------------| +| `favicon-16.svg` | 16×16 px | 1x | Вкладки браузера (старі браузери) | +| `favicon-32.svg` | 32×32 px | 1x | Стандартний фавікон | +| `favicon-64.svg` | 64×64 px | 1x-2x | Дисплеї High-DPI | +| `favicon-128.svg` | 128×128 px | 2x | Apple touch icon, закладки | +| `favicon-256.svg` | 256×256 px | 4x | Сучасні браузери, іконки PWA | + +## Інтеграція HTML + +### Базове налаштування фавіконів + +```html + + + + + + + + + +``` + +## Палітра кольорів + +### Основні кольори +- **Чорний**: `#000000` (Основний текст, обведення, південна стрілка) +- **Білий**: `#FFFFFF` (Світлі фони) +- **Сірий**: `#6B7280` (Вторинний текст, малі позначки) + +### Акцентний колір +- **Яскраво-зелений**: `#22C55E` (Північна стрілка, центральна точка, акцентні лінії — тільки для виділень, ніколи як фон) + +### Dark mode +- **Фон**: `#0A0A0A` (Майже чорний) + +### CSS-змінні +```css +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## Настанови з дизайну + +### Використання логотипу +- Використовуйте на білому або темному (#0A0A0A) фоні +- Масштабуйте пропорційно +- Залишайте вільний простір навколо (мінімум: висота логотипу / 2) +- Використовуйте надані light/dark варіанти для відповідних фонів + +### Доступність +- Високі коефіцієнти контрасту (WCAG AA — мінімум 4.5:1) +- Чисті геометричні форми, розпізнавані при будь-якому розмірі +- Масштабований векторний формат +- Без тексту в іконках (текст додається окремо) +- Без залежності від червоно-зеленого розрізнення кольорів + +## Атрибуція + +Ці ресурси є частиною проєкту Claude How To. + +**Ліцензія**: MIT (див. файл LICENSE проєкту) + +## Історія версій + +- **v3.0** (Лютий 2026): Дизайн компас-дужка з палітрою Чорний/Білий/Сірий + Зелений акцент +- **v2.0** (Січень 2026): Дизайн 12-променевого зоряного спалаху в стилі Claude з смарагдовою палітрою +- **v1.0** (Січень 2026): Оригінальний дизайн іконки прогресії на основі шестикутника + +--- +**Останнє оновлення**: Лютий 2026 +**Поточна версія**: 3.0 (Компас-дужка) diff --git a/uk/scripts/README.md b/uk/scripts/README.md new file mode 100644 index 0000000..d43c273 --- /dev/null +++ b/uk/scripts/README.md @@ -0,0 +1,120 @@ + + + Claude How To + + +# Скрипт збірки EPUB + +Збірка EPUB-книги з markdown-файлів Claude How-To. + +## Функції + +- Організує розділи за структурою каталогів (01-slash-commands, 02-memory тощо) +- Рендерить Mermaid-діаграми як PNG-зображення через Kroki.io API +- Асинхронне паралельне завантаження — рендерить усі діаграми одночасно +- Генерує обкладинку з логотипу проєкту +- Конвертує внутрішні markdown-посилання у посилання на розділи EPUB +- Суворий режим помилок — падає, якщо діаграма не може бути відрендерена + +## Вимоги + +- Python 3.10+ +- [uv](https://github.com/astral-sh/uv) +- Інтернет-з'єднання для рендерингу Mermaid-діаграм + +## Швидкий старт + +```bash +# Simplest way - uv handles everything +uv run scripts/build_epub.py +``` + +## Налаштування розробки + +```bash +# Create virtual environment +uv venv + +# Activate and install dependencies +source .venv/bin/activate +uv pip install -r requirements-dev.txt + +# Run tests +pytest scripts/tests/ -v + +# Run the script +python scripts/build_epub.py +``` + +## Параметри командного рядка + +``` +usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose] + [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT] + +options: + -h, --help show this help message and exit + --root, -r ROOT Root directory (default: repo root) + --output, -o OUTPUT Output path (default: claude-howto-guide.epub) + --verbose, -v Enable verbose logging + --timeout TIMEOUT API timeout in seconds (default: 30) + --max-concurrent N Max concurrent requests (default: 10) +``` + +## Приклади + +```bash +# Build with verbose output +uv run scripts/build_epub.py --verbose + +# Custom output location +uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub + +# Limit concurrent requests (if rate-limited) +uv run scripts/build_epub.py --max-concurrent 5 +``` + +## Вивід + +Створює `claude-howto-guide.epub` у кореневому каталозі репозиторію. + +EPUB включає: +- Обкладинку з логотипом проєкту +- Зміст з вкладеними секціями +- Весь markdown-контент, конвертований у EPUB-сумісний HTML +- Mermaid-діаграми, відрендерені як PNG-зображення + +## Запуск тестів + +```bash +# With virtual environment +source .venv/bin/activate +pytest scripts/tests/ -v + +# Or with uv directly +uv run --with pytest --with pytest-asyncio \ + --with ebooklib --with markdown --with beautifulsoup4 \ + --with httpx --with pillow --with tenacity \ + pytest scripts/tests/ -v +``` + +## Залежності + +Керуються через PEP 723 inline script metadata: + +| Пакет | Призначення | +|-------|-------------| +| `ebooklib` | Генерація EPUB | +| `markdown` | Конвертація Markdown → HTML | +| `beautifulsoup4` | Парсинг HTML | +| `httpx` | Асинхронний HTTP-клієнт | +| `pillow` | Генерація обкладинки | +| `tenacity` | Логіка повторних спроб | + +## Усунення проблем + +**Збірка падає з мережевою помилкою**: Перевірте інтернет-з'єднання та стан Kroki.io. Спробуйте `--timeout 60`. + +**Обмеження частоти**: Зменште паралельні запити з `--max-concurrent 3`. + +**Відсутній логотип**: Скрипт генерує текстову обкладинку, якщо `claude-howto-logo.png` не знайдено.