Add Vietnamese (Tiếng Việt) Localization (#42)
* feat(i18n): add Vietnamese localization infrastructure Add comprehensive infrastructure for Vietnamese translation of the claude-howto documentation: Features: - Parallel vi/ directory structure for Vietnamese content - Modified build_epub.py with --lang flag for Vietnamese EPUB - Vietnamese-specific pre-commit hooks for quality checks - Translation support files (glossary, style guide, queue tracker) - sync_translations.py script to detect outdated translations Infrastructure: - vi/ directory with all 10 module subdirectories - TRANSLATION_NOTES.md: comprehensive glossary and style guide - TRANSLATION_QUEUE.md: progress tracking for 66+ files - vi/README.md: Vietnamese landing page EPUB Build: - Added --lang CLI flag (en/vi) to build_epub.py - Language-specific metadata (title, subtitle) - Automatic root path adjustment for vi/ directory - Dynamic output filename (claude-howto-guide-vi.epub) Quality Assurance: - Vietnamese markdown linting - Vietnamese cross-reference checking - Vietnamese Mermaid syntax validation - Vietnamese link checking - Vietnamese EPUB build validation Ready for translation work to begin. * feat(vi): translate INDEX.md to Vietnamese Complete Vietnamese translation of INDEX.md - the comprehensive index of all example files in the repository. Translation follows vi/TRANSLATION_NOTES.md guidelines: - Technical terms kept per glossary (slash command → "lệnh slash") - File paths and code blocks preserved in English - Table structure and formatting maintained - All 882 lines translated Content includes: - Complete file tree (10 modules, 100+ files) - Feature coverage matrix - Quick start guides by use case - Learning path progression - Search by keyword sections Progress: 1/5 core documents completed * feat(vi): translate CATALOG.md to Vietnamese Complete Vietnamese translation of CATALOG.md - the quick reference guide to all Claude Code features. Translation follows vi/TRANSLATION_NOTES.md guidelines: - Technical terms kept per glossary (slash command → "lệnh slash") - All command names preserved (/help, /optimize, etc.) - Code blocks, JSON examples, and bash commands unchanged - All tables and formatting maintained - 517 lines translated with complete feature coverage Content includes: - Summary statistics (99 built-in + 43 examples = 117 total) - Complete built-in commands reference (55+ commands) - Custom commands examples (8 commands) - Permission modes (6 modes) - Subagents (6 built-in + 10 custom) - Skills (5 bundled + 4 custom) - Plugins (3 complete plugins) - MCP servers (1 built-in + 8 common servers) - Hooks (25 events + 7 example hooks) - Memory files (7 types) - New features (March 2026) - 17 new features - Installation priority guide - Complete one-command installation Progress: 2/5 core documents completed * docs(vi): translate learning roadmap to Vietnamese - Add complete Vietnamese translation of LEARNING-ROADMAP.md (747 lines) - Include self-assessment quiz for level determination - Translate three learning levels: Beginner, Intermediate, Advanced - Translate all milestones (1A, 1B, 2A, 2B, 3A, 3B) with hands-on exercises - Preserve Mermaid diagram for learning path visualization - Maintain progress tracking checklists and learning tips * docs(vi): translate quick reference guide to Vietnamese - Add complete Vietnamese translation of QUICK_REFERENCE.md (507 lines) - Include installation quick commands for all features - Translate feature cheat sheet with usage examples - Translate common use cases (code review, documentation, DevOps, etc.) - Preserve all code snippets, commands, and file paths in English - Maintain file locations reference diagram - Include learning path and new features (March 2026) sections - Keep tips & tricks, feature matrix, and checklist intact * docs(vi): translate module 01 - slash commands to Vietnamese - Add complete Vietnamese translation of 01-slash-commands/README.md (553 lines) - Translate slash commands overview and architecture - Include 55+ built-in commands reference table with Vietnamese descriptions - Translate bundled skills section (5 skills) - Document custom commands (now skills) migration path - Include frontmatter reference, arguments, and dynamic context sections - Preserve all command names, code examples, and Mermaid diagrams - Translate 8 available commands in folder with usage examples - Include installation, troubleshooting, and best practices sections * docs(vi): update translation queue progress - Module 01 README done - Mark 01-slash-commands/README.md as completed (2026-04-02) - Update Module 01 progress: 1/9 files (11%) - Update overall progress: 6/66 files (9%) - Update Priority 2 progress: 1/31 files (3%) - Add recent completion note to queue header * docs(vi): translate slash command - commit to Vietnamese - Translate commit.md slash command to Vietnamese - Keep all git commands and technical syntax intact - Translate instructions and descriptions - Maintain conventional commits format documentation * docs(vi): translate slash command - doc-refactor to Vietnamese - Translate doc-refactor.md slash command to Vietnamese - Keep all technical terms and file paths intact - Translate documentation refactoring instructions - Maintain structure and numbering * docs(vi): translate slash command - generate-api-docs to Vietnamese - Translate generate-api-docs.md slash command to Vietnamese - Keep all technical terms and file paths intact - Translate API documentation generation instructions - Maintain output format specifications * docs(vi): translate slash command - optimize to Vietnamese - Translate optimize.md slash command to Vietnamese - Keep all technical terms and code concepts intact - Translate code optimization instructions - Maintain issue priority and response format * docs(vi): translate slash command - pr to Vietnamese - Translate pr.md slash command to Vietnamese - Keep all commands and technical syntax intact - Translate PR preparation checklist instructions - Maintain conventional commits format documentation * docs(vi): translate slash command - push-all to Vietnamese - Translate push-all.md slash command to Vietnamese (153 lines) - Keep all git commands and technical syntax intact - Translate comprehensive workflow with safety checks - Maintain API key validation patterns and error handling - Preserve when to use/avoid sections and alternatives * docs(vi): translate slash command - setup-ci-cd to Vietnamese - Translate setup-ci-cd.md slash command to Vietnamese - Keep all tool names and technical terms intact - Translate CI/CD pipeline implementation instructions - Maintain pre-commit hooks and GitHub Actions sections * docs(vi): translate slash command - unit-test-expand to Vietnamese - Translate unit-test-expand.md slash command to Vietnamese - Keep all framework names and technical terms intact - Translate test coverage expansion instructions - Maintain testing frameworks and scenario sections * docs(vi): update translation queue - Module 01 complete (100%) - Mark all 9 Module 01 files as completed (2026-04-02) - Update Module 01 progress: 9/9 files (100%) ✅ - Update overall progress: 14/66 files (21%) - Update Priority 2 progress: 9/31 files (29%) - Update header with Module 01 completion milestone Module 01: Slash Commands - All files translated: ✅ README.md (overview, built-in commands, skills) ✅ commit.md (git commit with context) ✅ doc-refactor.md (documentation restructuring) ✅ generate-api-docs.md (API documentation generator) ✅ optimize.md (code optimization analysis) ✅ pr.md (pull request preparation) ✅ push-all.md (stage, commit, push with safety) ✅ setup-ci-cd.md (CI/CD pipeline implementation) ✅ unit-test-expand.md (test coverage expansion) * docs(vi): translate module 02 - memory guide to Vietnamese - Add complete Vietnamese translation of 02-memory/README.md (1162 lines) - Translate memory system overview and architecture - Include quick reference for memory commands (/init, /memory, #) - Document complete memory hierarchy (8 levels with precedence) - Translate auto memory section with architecture diagrams - Include practical examples (project, directory-specific, personal memory) - Add best practices, installation instructions, and troubleshooting - Preserve all code examples, file paths, and technical terms - Maintain Mermaid diagrams and tables * docs(vi): translate example project CLAUDE.md to Vietnamese - Translate project-CLAUDE.md example memory file - Keep all technical terms, commands, and code style intact - Translate descriptions and explanations - Maintain project configuration structure * docs(vi): translate example personal CLAUDE.md to Vietnamese - Translate personal-CLAUDE.md example memory file - Keep all technical terms, tools, and preferences intact - Translate descriptions and explanations - Maintain personal preferences structure * docs(vi): translate example directory-specific CLAUDE.md to Vietnamese - Translate directory-api-CLAUDE.md example memory file - Keep all technical terms, API standards, and code examples intact - Translate descriptions and explanations - Maintain API module standards structure * docs(vi): update translation queue - Module 02 complete (100%) - Mark all 4 Module 02 files as completed (2026-04-02) - Update Module 02 progress: 4/4 files (100%) ✅ - Update overall progress: 18/66 files (27%) - Update Priority 2 progress: 13/31 files (42%) - Update header with Module 02 completion milestone Module 02: Memory - All files translated: ✅ README.md (1162 lines - comprehensive memory guide) ✅ project-CLAUDE.md (example project memory) ✅ personal-CLAUDE.md (example personal preferences) ✅ directory-api-CLAUDE.md (example directory-specific rules) * docs(vi): translate module 03 - skills guide to Vietnamese - Add complete Vietnamese translation of 03-skills/README.md (805 lines) - Translate Agent Skills overview and architecture - Include progressive disclosure loading mechanism (3 levels) - Document skill types, locations, and automatic discovery - Translate skill creation process and SKILL.md format - Include required and optional frontmatter fields - Document skill content types (reference vs task) - Translate controlling skill invocation and string substitutions - Include dynamic context injection with shell commands - Document running skills in subagents with context: fork - Translate 6 practical examples with directory structures - Add supporting files, management, and best practices sections - Preserve all code examples, YAML frontmatter, and Mermaid diagrams - Maintain tables, troubleshooting guides, and security considerations * docs(vi): translate skill - blog-draft to Vietnamese - Translate blog-draft/SKILL.md to Vietnamese (275 lines) - Keep all workflow steps and technical structure intact - Translate instructions and descriptions - Maintain version tracking and file structure - Preserve all markdown formatting and code examples * docs(vi): translate skill - brand-voice to Vietnamese - Translate brand-voice/SKILL.md to Vietnamese (73 lines) - Keep brand identity, tone, and vocabulary intact - Translate writing guidelines and examples - Maintain preferred/avoided terms sections - Preserve good/bad examples with explanations * docs(vi): translate skill - claude-md to Vietnamese - Translate claude-md/SKILL.md to Vietnamese (213 lines) - Keep all golden rules and core principles intact - Translate execution flow and content strategy - Maintain WHAT/WHY/HOW structure - Preserve quality constraints and validation checklist - Keep anti-patterns and output format sections * docs(vi): translate skill - code-review to Vietnamese - Translate code-review/SKILL.md to Vietnamese (71 lines) - Keep all review categories and template intact - Translate security, performance, quality, maintainability sections - Maintain review template structure - Preserve version history * docs(vi): translate skill - refactor to Vietnamese - Translate refactor/SKILL.md to Vietnamese (427 lines) - Keep all Martin Fowler refactoring methodology intact - Translate 6-phase workflow with detailed steps - Maintain core principles and safety rules - Preserve code smell catalog and refactoring techniques - Keep quick start example with before/after code - Maintain version history and references sections * docs(vi): update translation queue - Module 03 complete (100%) - Mark all 6 Module 03 files as completed (2026-04-02) - Update Module 03 progress: 6/6 files (100%) ✅ - Update overall progress: 24/66 files (36%) - Update Priority 2 progress: 19/31 files (61%) - Update header with Module 03 completion milestone Module 03: Skills - All files translated: ✅ README.md (805 lines - comprehensive skills guide) ✅ blog-draft/SKILL.md (275 lines - blog post creation workflow) ✅ brand-voice/SKILL.md (73 lines - brand voice consistency) ✅ claude-md/SKILL.md (213 lines - CLAUDE.md best practices) ✅ code-review/SKILL.md (71 lines - comprehensive code review) ✅ refactor/SKILL.md (427 lines - Fowler refactoring methodology) * docs(vi): translate Module 04 Subagents README Complete Vietnamese translation of subagents reference guide: - Configuration and built-in subagents (general-purpose, Plan, Explore, Bash, statusline-setup, Claude Code Guide) - Agent management with /agents command - Automatic delegation vs explicit invocation - Resumable agents and chaining - Persistent memory across agent sessions - Background subagents for parallel work - Worktree isolation for safe experimentation - Agent Teams (experimental feature) - Best practices and usage patterns * docs(vi): complete Module 04 Subagents translation Translate all 6 subagent example definitions: - code-reviewer.md: Expert code review specialist - debugger.md: Root cause analysis and debugging - documentation-writer.md: Technical documentation creation - implementation-agent.md: Full-stack feature implementation - secure-reviewer.md: Security-focused code review - test-engineer.md: Comprehensive test coverage Update translation queue progress: - Module 04: 7/7 files (100%) ✅ - Overall: 31/66 files (47%) - Next: Module 05 (MCP) * docs(vi): complete Module 05 MCP translation Translate comprehensive MCP (Model Context Protocol) guide: - Overview and architecture diagrams - Installation methods (HTTP, Stdio, SSE, WebSocket) - OAuth 2.0 authentication support - MCP tool search and dynamic updates - Elicitation and prompt slash commands - Configuration management (local, project, user scopes) - Practical examples (GitHub, Database, Filesystem, Slack MCPs) - MCP vs Memory decision matrix - Code execution approach for solving context bloat - MCPorter runtime reference - Security best practices and troubleshooting Translate 4 MCP configuration JSON examples: - filesystem-mcp.json: File operations - github-mcp.json: GitHub integration - database-mcp.json: SQL queries - multi-mcp.json: Multiple servers configuration Update translation queue progress: - Module 05: 5/5 files (100%) ✅ - Overall: 36/66 files (55%) - Next: Module 06 (Hooks) * docs(vi): complete Module 06 Hooks translation Translate comprehensive Hooks guide: - Overview and architecture - Configuration structure (user, project, local scopes) - Four hook types: command, HTTP, prompt, agent - 25 hook events with matcher patterns - Component-scoped hooks and subagent frontmatter - JSON input/output format and exit codes - Environment variables and best practices - Security considerations and debugging - Installation instructions Copy 9 hook example files (code, no translation needed): - format-code.sh: Auto-format code after write/edit - log-bash.sh: Bash command logging - notify-team.sh: Team notifications - pre-commit.sh: Pre-commit validation - security-scan.sh: Security scanning - validate-prompt.sh: Prompt validation - context-tracker.py: Token usage tracking - context-tracker-tiktoken.py: Accurate token counting Update translation queue progress: - Module 06: 9/9 files (100%) ✅ - Overall: 45/67 files (67%) - Next: Module 07 (Plugins) * docs(vi): complete Module 07 Plugins translation Translate comprehensive Plugins guide: - Overview and architecture diagrams - Plugin loading process and lifecycle - Plugin types (Official, Community, Organization, Personal) - Plugin definition structure and manifest - Plugin structure example with all directories - LSP server configuration and examples - Plugin options (v2.1.83+) with userConfig - Persistent plugin data via CLAUDE_PLUGIN_DATA - Inline plugins via settings (v2.1.80+) - Standalone vs Plugin approach comparison - Practical examples (PR Review, DevOps, Documentation plugins) - Plugin marketplace and distribution - Marketplace configuration and definition schema - Plugin source types and distribution methods - Plugin CLI commands and installation methods - Plugin features comparison table - Testing, hot-reload, and managed settings - Plugin security restrictions - Publishing workflow and best practices - Complete troubleshooting guide Copy all plugin subdirectories (code, no translation needed): - devops-automation/: Deployment workflows, incident management - documentation/: API docs, README generation, templates - pr-review/: Pull request review automation Update translation queue progress: - Module 07: 10+/10+ files (100%) ✅ - Overall: 55+/67 files (82%) - Next: Module 08-10 (Checkpoints, Advanced Features, CLI) * docs(vi): complete Modules 08-10 translation Module 08: Checkpoints and Rewind (2 files) - Overview and architecture - Access methods (keyboard shortcut, slash command) - Five rewind options (restore code+conversation, conversation, code, summarize, cancel) - Automatic checkpoints and retention policies - Use cases and practical examples - Integration with git and best practices Module 09: Advanced Features (3 files) - Planning Mode: Two-phase implementation approach - Extended Thinking: Deep reasoning for complex problems - Auto Mode: Background safety classifier - Background Tasks, Scheduled Tasks - Permission Modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) - Print Mode, Session Management - Voice Dictation, Channels, Remote Control - Web Sessions, Desktop App, Task List - Git Worktrees, Sandboxing, Managed Settings Module 10: CLI Reference (1 file) - CLI commands reference - Core flags and options - Interactive vs Print Mode - Model selection and configuration - System prompt customization - Tool & permission management - Output formats and scripting Update translation queue progress: - Modules 08-10: 6/6 files (100%) ✅ - All Modules 01-10: 61+/61+ files (100%) ✅ - Overall: 61+/67 files (91%) - Remaining: Supporting docs (6 files) * docs(vi): complete supporting documentation translation Translate all 5 supporting documents: - CONTRIBUTING.md: Contribution guidelines - SECURITY.md: Security policy and vulnerability reporting - CODE_OF_CONDUCT.md: Community standards and harassment policy - STYLE_GUIDE.md: Documentation formatting conventions - CHANGELOG.md: Version history (v2.2.0, v2.1.1, v2.1.0, v2.0.0) Update translation queue to 100% completion: - All Modules 01-10: 61+ files (100%) ✅ - Supporting Docs: 5/5 files (100%) ✅ - Overall: 67+/67 files (100%) ✅ - Status: HOÀN THÀNH ✅ * fix(vi): fix mermaid syntax and broken cross-references in Vietnamese translation Fix invalid `#` comment in mermaid block (use `%%` instead) and update cross-reference script to support Unicode/Vietnamese diacritics in anchor generation. Fix broken anchor links across vi/ documentation files. * fix(vi): remove inline mermaid comment causing parse error Inline %% comments on node definition lines are not supported by the mermaid parser. The surrounding HTML comment already explains this is an incorrect example.
This commit is contained in:
Thiên Toán
1871
vi/09-advanced-features/README.md
Normal file
1871
vi/09-advanced-features/README.md
Normal file
File diff suppressed because it is too large
Load Diff
270
vi/09-advanced-features/config-examples.json
Normal file
270
vi/09-advanced-features/config-examples.json
Normal file
@@ -0,0 +1,270 @@
|
||||
{
|
||||
"description": "Example Claude Code configurations for different use cases",
|
||||
|
||||
"examples": {
|
||||
"development": {
|
||||
"name": "Development Environment",
|
||||
"description": "Configuration for active development work",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.7
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"complexityThreshold": 3,
|
||||
"requireApproval": true
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "unrestricted"
|
||||
},
|
||||
"backgroundTasks": {
|
||||
"enabled": true,
|
||||
"maxConcurrentTasks": 3
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse:Write": "prettier --write ${file_path}",
|
||||
"PostToolUse:Write": "eslint ${file_path}",
|
||||
"PreCommit": "npm test"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"code_review": {
|
||||
"name": "Code Review Mode",
|
||||
"description": "Configuration for reviewing code without modifications",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.3
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "plan"
|
||||
},
|
||||
"extendedThinking": {
|
||||
"enabled": true,
|
||||
"showThinkingProcess": true
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": false
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"learning": {
|
||||
"name": "Learning Mode",
|
||||
"description": "Configuration for learning and experimentation",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.5
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "confirm"
|
||||
},
|
||||
"extendedThinking": {
|
||||
"enabled": true,
|
||||
"showThinkingProcess": true
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"requireApproval": true,
|
||||
"showTimeEstimates": true
|
||||
},
|
||||
"checkpoints": {
|
||||
"autoCheckpoint": true
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"production": {
|
||||
"name": "Production Deployment",
|
||||
"description": "Configuration for production operations with safety checks",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-opus-4",
|
||||
"temperature": 0.1
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "confirm",
|
||||
"requireConfirmationFor": ["Bash", "Git", "Write", "Edit"]
|
||||
},
|
||||
"hooks": {
|
||||
"PreCommit": "npm test && npm run lint && npm run build",
|
||||
"PrePush": "npm run test:e2e",
|
||||
"PostPush": "~/.claude/hooks/notify-team.sh"
|
||||
},
|
||||
"checkpoints": {
|
||||
"autoCheckpoint": true
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"requireApproval": true
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"ci_cd": {
|
||||
"name": "CI/CD Pipeline",
|
||||
"description": "Configuration for automated CI/CD operations",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "unrestricted"
|
||||
},
|
||||
"headless": {
|
||||
"exitOnError": true,
|
||||
"verbose": true,
|
||||
"timeout": 3600
|
||||
},
|
||||
"logging": {
|
||||
"level": "debug",
|
||||
"file": "./ci-claude.log"
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": false,
|
||||
"requireApproval": false
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"security_audit": {
|
||||
"name": "Security Audit",
|
||||
"description": "Configuration for security-focused code analysis",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-opus-4",
|
||||
"temperature": 0.2
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "plan"
|
||||
},
|
||||
"extendedThinking": {
|
||||
"enabled": true,
|
||||
"showThinkingProcess": true,
|
||||
"minThinkingTime": 10
|
||||
},
|
||||
"hooks": {
|
||||
"PostToolUse:Read": "~/.claude/hooks/security-scan.sh ${file_path}"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"performance_optimization": {
|
||||
"name": "Performance Optimization",
|
||||
"description": "Configuration for performance analysis and optimization",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.4
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"requireApproval": true
|
||||
},
|
||||
"backgroundTasks": {
|
||||
"enabled": true,
|
||||
"maxConcurrentTasks": 5
|
||||
},
|
||||
"checkpoints": {
|
||||
"autoCheckpoint": true
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"pair_programming": {
|
||||
"name": "Pair Programming",
|
||||
"description": "Configuration for collaborative development",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.6
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "confirm"
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"requireApproval": true,
|
||||
"showTimeEstimates": true
|
||||
},
|
||||
"extendedThinking": {
|
||||
"enabled": true,
|
||||
"showThinkingProcess": true
|
||||
},
|
||||
"ui": {
|
||||
"compactMode": false,
|
||||
"showProgress": true
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"refactoring": {
|
||||
"name": "Large Refactoring",
|
||||
"description": "Configuration for major refactoring work",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-opus-4",
|
||||
"temperature": 0.3
|
||||
},
|
||||
"planning": {
|
||||
"autoEnter": true,
|
||||
"requireApproval": true,
|
||||
"showTimeEstimates": true
|
||||
},
|
||||
"checkpoints": {
|
||||
"autoCheckpoint": true
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse:Edit": "~/.claude/hooks/backup-file.sh ${file_path}",
|
||||
"PostToolUse:Edit": "npm test -- --findRelatedTests ${file_path}"
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "confirm"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"autonomous": {
|
||||
"name": "Autonomous Development",
|
||||
"description": "Configuration for autonomous work with auto mode safety checks",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-6",
|
||||
"temperature": 0.5
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "auto"
|
||||
},
|
||||
"sandbox": {
|
||||
"enabled": true,
|
||||
"failIfUnavailable": false
|
||||
},
|
||||
"backgroundTasks": {
|
||||
"enabled": true,
|
||||
"maxConcurrentTasks": 3
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"documentation": {
|
||||
"name": "Documentation Writing",
|
||||
"description": "Configuration for writing documentation",
|
||||
"config": {
|
||||
"general": {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"temperature": 0.7
|
||||
},
|
||||
"permissions": {
|
||||
"mode": "unrestricted"
|
||||
},
|
||||
"hooks": {
|
||||
"PostToolUse:Write": "markdownlint ${file_path}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
533
vi/09-advanced-features/planning-mode-examples.md
Normal file
533
vi/09-advanced-features/planning-mode-examples.md
Normal file
@@ -0,0 +1,533 @@
|
||||
# Planning Mode Examples
|
||||
|
||||
Real-world examples demonstrating effective use of planning mode in Claude Code.
|
||||
|
||||
## Example 1: Building a REST API
|
||||
|
||||
### Without Planning Mode
|
||||
|
||||
```
|
||||
User: Build a REST API for a blog
|
||||
|
||||
Claude: I'll create the API...
|
||||
[Starts coding immediately, may miss requirements]
|
||||
```
|
||||
|
||||
### With Planning Mode
|
||||
|
||||
```
|
||||
User: /plan Build a REST API for a blog
|
||||
|
||||
Claude: Let me create a comprehensive plan for the blog API.
|
||||
|
||||
## Blog REST API Implementation Plan
|
||||
|
||||
### Phase 1: Project Setup (15 min)
|
||||
1. Initialize Node.js project with Express
|
||||
2. Set up TypeScript configuration
|
||||
3. Install dependencies (express, pg, jwt, joi)
|
||||
4. Configure environment variables
|
||||
5. Set up project structure
|
||||
|
||||
### Phase 2: Database Layer (30 min)
|
||||
6. Design database schema
|
||||
- users table (id, email, password_hash, created_at)
|
||||
- posts table (id, user_id, title, content, published, created_at, updated_at)
|
||||
- comments table (id, post_id, user_id, content, created_at)
|
||||
7. Create migration files
|
||||
8. Set up database connection pool
|
||||
9. Implement database models
|
||||
|
||||
### Phase 3: Authentication (45 min)
|
||||
10. Implement user registration endpoint
|
||||
11. Implement login endpoint with JWT
|
||||
12. Create authentication middleware
|
||||
13. Add password hashing with bcrypt
|
||||
14. Implement token refresh logic
|
||||
|
||||
### Phase 4: Posts API (40 min)
|
||||
15. GET /api/posts - List all published posts (with pagination)
|
||||
16. GET /api/posts/:id - Get single post
|
||||
17. POST /api/posts - Create new post (auth required)
|
||||
18. PUT /api/posts/:id - Update post (auth required, ownership check)
|
||||
19. DELETE /api/posts/:id - Delete post (auth required, ownership check)
|
||||
20. GET /api/users/:id/posts - Get user's posts
|
||||
|
||||
### Phase 5: Comments API (30 min)
|
||||
21. GET /api/posts/:id/comments - Get post comments
|
||||
22. POST /api/posts/:id/comments - Add comment (auth required)
|
||||
23. DELETE /api/comments/:id - Delete comment (auth required, ownership check)
|
||||
|
||||
### Phase 6: Validation & Error Handling (30 min)
|
||||
24. Add request validation with Joi
|
||||
25. Implement global error handler
|
||||
26. Add input sanitization
|
||||
27. Implement rate limiting
|
||||
|
||||
### Phase 7: Testing (60 min)
|
||||
28. Write unit tests for models
|
||||
29. Write integration tests for auth endpoints
|
||||
30. Write integration tests for posts endpoints
|
||||
31. Write integration tests for comments endpoints
|
||||
32. Achieve 80%+ code coverage
|
||||
|
||||
### Phase 8: Documentation & Deployment (30 min)
|
||||
33. Generate API documentation with Swagger
|
||||
34. Create README with setup instructions
|
||||
35. Add Docker configuration
|
||||
36. Set up CI/CD pipeline
|
||||
|
||||
**Estimated Time**: 4.5 hours
|
||||
**Files to Create**: ~25
|
||||
**Key Technologies**: Express, PostgreSQL, JWT, TypeScript
|
||||
|
||||
**API Endpoints Summary**:
|
||||
- Authentication: 2 endpoints
|
||||
- Posts: 6 endpoints
|
||||
- Comments: 3 endpoints
|
||||
- Total: 11 endpoints
|
||||
|
||||
Ready to proceed? (yes/no/modify)
|
||||
|
||||
User: yes
|
||||
|
||||
Claude: Starting Phase 1: Project Setup...
|
||||
[Implements each phase systematically]
|
||||
```
|
||||
|
||||
## Example 2: Database Migration
|
||||
|
||||
### With Planning Mode
|
||||
|
||||
```
|
||||
User: /plan Migrate from MongoDB to PostgreSQL
|
||||
|
||||
Claude: This is a complex migration. Let me create a detailed plan.
|
||||
|
||||
## MongoDB to PostgreSQL Migration Plan
|
||||
|
||||
### Phase 1: Analysis & Preparation (Day 1)
|
||||
1. Analyze current MongoDB schema
|
||||
2. Identify data relationships and constraints
|
||||
3. Document current data volume and growth rate
|
||||
4. Design equivalent PostgreSQL schema
|
||||
5. Plan data type mappings
|
||||
6. Identify potential migration challenges
|
||||
|
||||
### Phase 2: PostgreSQL Setup (Day 1)
|
||||
7. Set up PostgreSQL database
|
||||
8. Create schema with tables, indexes, constraints
|
||||
9. Set up connection pooling
|
||||
10. Configure backup strategy
|
||||
|
||||
### Phase 3: Dual-Write Implementation (Day 2-3)
|
||||
11. Create database abstraction layer
|
||||
12. Implement dual-write to both databases
|
||||
13. Add data consistency checks
|
||||
14. Deploy dual-write to staging
|
||||
15. Monitor for issues
|
||||
|
||||
### Phase 4: Data Migration (Day 4)
|
||||
16. Create data export scripts for MongoDB
|
||||
17. Create data import scripts for PostgreSQL
|
||||
18. Implement data transformation logic
|
||||
19. Run initial migration on copy of production data
|
||||
20. Validate migrated data integrity
|
||||
|
||||
### Phase 5: Gradual Cutover (Day 5-7)
|
||||
21. Enable dual-write in production
|
||||
22. Migrate historical data in batches
|
||||
23. Continuously validate data consistency
|
||||
24. Monitor both databases
|
||||
25. Fix any data synchronization issues
|
||||
|
||||
### Phase 6: PostgreSQL Primary (Day 8)
|
||||
26. Switch read operations to PostgreSQL
|
||||
27. Monitor query performance
|
||||
28. Optimize slow queries
|
||||
29. Continue dual-write for safety
|
||||
|
||||
### Phase 7: MongoDB Retirement (Day 9-10)
|
||||
30. Stop writing to MongoDB
|
||||
31. Keep MongoDB as backup for 2 weeks
|
||||
32. Remove MongoDB dependencies from code
|
||||
33. Archive MongoDB data
|
||||
34. Decommission MongoDB instance
|
||||
|
||||
**Estimated Time**: 10 days
|
||||
**Risk Level**: High
|
||||
**Rollback Strategy**: Keep MongoDB running with dual-write
|
||||
**Success Criteria**:
|
||||
- Zero data loss
|
||||
- <5% performance regression
|
||||
- All tests passing
|
||||
|
||||
**Key Risks**:
|
||||
1. Data inconsistency during migration
|
||||
2. Query performance degradation
|
||||
3. Application downtime
|
||||
4. Data loss
|
||||
|
||||
**Mitigation**:
|
||||
- Dual-write pattern for safety
|
||||
- Gradual cutover
|
||||
- Continuous monitoring
|
||||
- Quick rollback capability
|
||||
|
||||
Proceed with this plan? (yes/no/modify)
|
||||
|
||||
User: Modify - let's add a rollback plan for each phase
|
||||
|
||||
Claude: Updated plan with rollback procedures for each phase...
|
||||
```
|
||||
|
||||
## Example 3: Frontend Refactoring
|
||||
|
||||
```
|
||||
User: /plan Refactor our React app from class components to hooks
|
||||
|
||||
Claude: I'll create a systematic refactoring plan.
|
||||
|
||||
## React Class to Hooks Migration Plan
|
||||
|
||||
### Phase 1: Preparation & Analysis (2 hours)
|
||||
1. Audit all class components (find all .jsx/.tsx files)
|
||||
2. Categorize by complexity:
|
||||
- Simple (state only): ~15 components
|
||||
- Medium (lifecycle methods): ~23 components
|
||||
- Complex (multiple lifecycle, refs): ~8 components
|
||||
3. Identify third-party libraries that need updates
|
||||
4. Create component dependency graph
|
||||
5. Plan migration order (leaf nodes first)
|
||||
|
||||
### Phase 2: Setup & Tooling (1 hour)
|
||||
6. Update React to v18+
|
||||
7. Set up ESLint rules for hooks
|
||||
8. Create conversion templates
|
||||
9. Set up automated tests
|
||||
10. Create checkpoint before starting
|
||||
|
||||
### Phase 3: Migrate Simple Components (4 hours)
|
||||
11. Convert simple stateful components (15 components)
|
||||
12. Replace this.state with useState
|
||||
13. Replace this.setState with state setters
|
||||
14. Test each component after conversion
|
||||
15. Update tests
|
||||
|
||||
### Phase 4: Migrate Medium Components (8 hours)
|
||||
16. Convert components with lifecycle methods (23 components)
|
||||
17. Replace componentDidMount with useEffect
|
||||
18. Replace componentDidUpdate with useEffect
|
||||
19. Replace componentWillUnmount with useEffect cleanup
|
||||
20. Test thoroughly
|
||||
|
||||
### Phase 5: Migrate Complex Components (12 hours)
|
||||
21. Convert complex components (8 components)
|
||||
22. Replace refs with useRef
|
||||
23. Extract custom hooks for shared logic
|
||||
24. Handle edge cases (multiple useEffect)
|
||||
25. Extensive testing
|
||||
|
||||
### Phase 6: Shared Logic Extraction (6 hours)
|
||||
26. Identify duplicated logic across components
|
||||
27. Create custom hooks:
|
||||
- useAuth
|
||||
- useFetch
|
||||
- useLocalStorage
|
||||
- useDebounce
|
||||
28. Refactor components to use custom hooks
|
||||
29. Test custom hooks independently
|
||||
|
||||
### Phase 7: Performance Optimization (4 hours)
|
||||
30. Add React.memo where needed
|
||||
31. Optimize with useCallback
|
||||
32. Optimize with useMemo
|
||||
33. Profile and fix performance regressions
|
||||
|
||||
### Phase 8: Cleanup & Documentation (2 hours)
|
||||
34. Remove unused class component utilities
|
||||
35. Update documentation
|
||||
36. Update coding guidelines
|
||||
37. Create migration guide for team
|
||||
|
||||
**Estimated Time**: 5 days (39 hours)
|
||||
**Files to Modify**: 46 components
|
||||
**Risk Level**: Medium
|
||||
|
||||
**Migration Order**:
|
||||
1. Leaf components (no dependencies)
|
||||
2. Mid-level components
|
||||
3. Top-level container components
|
||||
4. App.jsx (last)
|
||||
|
||||
**Testing Strategy**:
|
||||
- Unit tests for each component
|
||||
- Integration tests for user flows
|
||||
- Visual regression tests
|
||||
- Performance benchmarks
|
||||
|
||||
**Success Metrics**:
|
||||
- All tests passing
|
||||
- No visual regressions
|
||||
- Performance maintained or improved
|
||||
- Bundle size not significantly increased
|
||||
|
||||
Proceed? (yes/no/modify)
|
||||
```
|
||||
|
||||
## Example 4: Security Implementation
|
||||
|
||||
```
|
||||
User: /plan Implement comprehensive security for our web app
|
||||
|
||||
Claude: Let me create a thorough security implementation plan.
|
||||
|
||||
## Web Application Security Implementation Plan
|
||||
|
||||
### Phase 1: Security Audit (Day 1)
|
||||
1. Run automated security scanners (npm audit, Snyk)
|
||||
2. Review dependencies for vulnerabilities
|
||||
3. Check OWASP Top 10 compliance
|
||||
4. Audit authentication flows
|
||||
5. Review data handling practices
|
||||
6. Document current security gaps
|
||||
|
||||
### Phase 2: Authentication Hardening (Day 2-3)
|
||||
7. Implement strong password requirements
|
||||
8. Add password strength meter
|
||||
9. Implement rate limiting on login
|
||||
10. Add account lockout after failed attempts
|
||||
11. Implement 2FA (TOTP)
|
||||
12. Add session management improvements
|
||||
13. Implement secure password reset flow
|
||||
|
||||
### Phase 3: Authorization & Access Control (Day 3-4)
|
||||
14. Implement RBAC (Role-Based Access Control)
|
||||
15. Add permission checks on all endpoints
|
||||
16. Implement principle of least privilege
|
||||
17. Add audit logging for sensitive operations
|
||||
18. Implement resource-level permissions
|
||||
|
||||
### Phase 4: Data Protection (Day 4-5)
|
||||
19. Implement encryption at rest (sensitive fields)
|
||||
20. Ensure TLS/SSL for all communications
|
||||
21. Implement secure session storage
|
||||
22. Add PII data masking in logs
|
||||
23. Implement data retention policies
|
||||
24. Add secure file upload handling
|
||||
|
||||
### Phase 5: Input Validation & Sanitization (Day 5-6)
|
||||
25. Implement input validation on all endpoints
|
||||
26. Add XSS protection (Content Security Policy)
|
||||
27. Implement SQL injection prevention (parameterized queries)
|
||||
28. Add CSRF protection
|
||||
29. Implement request size limits
|
||||
30. Add file upload type validation
|
||||
|
||||
### Phase 6: Security Headers & Configuration (Day 6)
|
||||
31. Add security headers:
|
||||
- Strict-Transport-Security
|
||||
- X-Content-Type-Options
|
||||
- X-Frame-Options
|
||||
- X-XSS-Protection
|
||||
- Content-Security-Policy
|
||||
32. Configure CORS properly
|
||||
33. Disable unnecessary HTTP methods
|
||||
34. Remove server version headers
|
||||
|
||||
### Phase 7: Monitoring & Logging (Day 7)
|
||||
35. Implement security event logging
|
||||
36. Add anomaly detection
|
||||
37. Set up intrusion detection
|
||||
38. Implement real-time alerting
|
||||
39. Create security dashboard
|
||||
|
||||
### Phase 8: Testing & Documentation (Day 8-9)
|
||||
40. Perform penetration testing
|
||||
41. Run security scanners
|
||||
42. Test all security features
|
||||
43. Create security documentation
|
||||
44. Train team on security practices
|
||||
45. Create incident response plan
|
||||
|
||||
### Phase 9: Compliance & Policies (Day 10)
|
||||
46. GDPR compliance check
|
||||
47. Create privacy policy
|
||||
48. Implement data subject rights
|
||||
49. Add cookie consent
|
||||
50. Create security policies documentation
|
||||
|
||||
**Estimated Time**: 10 days
|
||||
**Risk Level**: Critical
|
||||
**Priority**: High
|
||||
|
||||
**Security Improvements Summary**:
|
||||
- Authentication: 7 enhancements
|
||||
- Authorization: 5 enhancements
|
||||
- Data Protection: 6 enhancements
|
||||
- Input Validation: 6 enhancements
|
||||
- Infrastructure: 9 enhancements
|
||||
- Monitoring: 5 enhancements
|
||||
|
||||
**Compliance**: OWASP Top 10, GDPR
|
||||
|
||||
**Success Criteria**:
|
||||
- Zero critical vulnerabilities
|
||||
- All OWASP Top 10 mitigated
|
||||
- Security score >90/100
|
||||
- All pen test issues resolved
|
||||
|
||||
Proceed? (yes/no/modify)
|
||||
```
|
||||
|
||||
## Example 5: Performance Optimization
|
||||
|
||||
```
|
||||
User: /plan Optimize our slow e-commerce website
|
||||
|
||||
Claude: Let me create a comprehensive performance optimization plan.
|
||||
|
||||
## E-commerce Performance Optimization Plan
|
||||
|
||||
### Phase 1: Performance Audit (4 hours)
|
||||
1. Run Lighthouse audit
|
||||
2. Analyze Chrome DevTools performance profile
|
||||
3. Measure Core Web Vitals:
|
||||
- LCP (Largest Contentful Paint)
|
||||
- FID (First Input Delay)
|
||||
- CLS (Cumulative Layout Shift)
|
||||
4. Identify performance bottlenecks
|
||||
5. Create baseline performance metrics
|
||||
|
||||
**Current Metrics**:
|
||||
- LCP: 4.2s (target: <2.5s)
|
||||
- FID: 280ms (target: <100ms)
|
||||
- CLS: 0.25 (target: <0.1)
|
||||
- Page Load: 8.3s (target: <3s)
|
||||
|
||||
### Phase 2: Image Optimization (6 hours)
|
||||
6. Convert images to WebP format
|
||||
7. Implement responsive images
|
||||
8. Add lazy loading for images
|
||||
9. Optimize image sizes (compression)
|
||||
10. Implement CDN for images
|
||||
11. Add image placeholders
|
||||
|
||||
**Expected Impact**: -40% load time
|
||||
|
||||
### Phase 3: Code Splitting & Lazy Loading (8 hours)
|
||||
12. Implement route-based code splitting
|
||||
13. Lazy load non-critical components
|
||||
14. Split vendor bundles
|
||||
15. Optimize chunk sizes
|
||||
16. Implement dynamic imports
|
||||
17. Add preloading for critical resources
|
||||
|
||||
**Expected Impact**: -30% initial bundle size
|
||||
|
||||
### Phase 4: Caching Strategy (6 hours)
|
||||
18. Implement browser caching (Cache-Control)
|
||||
19. Add service worker for offline support
|
||||
20. Implement API response caching
|
||||
21. Add Redis cache for database queries
|
||||
22. Implement stale-while-revalidate
|
||||
23. Configure CDN caching
|
||||
|
||||
**Expected Impact**: -50% API response time
|
||||
|
||||
### Phase 5: Database Optimization (8 hours)
|
||||
24. Add database indexes
|
||||
25. Optimize slow queries (>100ms)
|
||||
26. Implement query result caching
|
||||
27. Add connection pooling
|
||||
28. Denormalize where appropriate
|
||||
29. Implement database read replicas
|
||||
|
||||
**Expected Impact**: -60% database query time
|
||||
|
||||
### Phase 6: Frontend Optimization (10 hours)
|
||||
30. Minimize and compress JavaScript
|
||||
31. Minimize and compress CSS
|
||||
32. Remove unused CSS (PurgeCSS)
|
||||
33. Implement critical CSS
|
||||
34. Defer non-critical JavaScript
|
||||
35. Reduce DOM size
|
||||
36. Optimize React rendering (memo, useMemo)
|
||||
37. Implement virtual scrolling for long lists
|
||||
|
||||
**Expected Impact**: -35% JavaScript execution time
|
||||
|
||||
### Phase 7: Network Optimization (4 hours)
|
||||
38. Enable HTTP/2
|
||||
39. Implement resource hints (preconnect, prefetch)
|
||||
40. Reduce number of HTTP requests
|
||||
41. Enable Brotli compression
|
||||
42. Optimize third-party scripts
|
||||
|
||||
**Expected Impact**: -25% network time
|
||||
|
||||
### Phase 8: Monitoring & Testing (4 hours)
|
||||
43. Set up performance monitoring (Datadog/New Relic)
|
||||
44. Add Real User Monitoring (RUM)
|
||||
45. Create performance budgets
|
||||
46. Set up automated Lighthouse CI
|
||||
47. Test on real devices
|
||||
|
||||
**Estimated Time**: 50 hours (2 weeks)
|
||||
|
||||
**Target Metrics** (90th percentile):
|
||||
- LCP: <2.0s (from 4.2s) ✅
|
||||
- FID: <50ms (from 280ms) ✅
|
||||
- CLS: <0.05 (from 0.25) ✅
|
||||
- Page Load: <2.5s (from 8.3s) ✅
|
||||
|
||||
**Expected Revenue Impact**:
|
||||
- 100ms faster = 1% conversion increase
|
||||
- Target: 5.8s improvement = ~58% conversion increase
|
||||
- Estimated additional revenue: Significant
|
||||
|
||||
**Priority Order**:
|
||||
1. Image optimization (quick wins)
|
||||
2. Code splitting (high impact)
|
||||
3. Caching (high impact)
|
||||
4. Database optimization (critical)
|
||||
5. Frontend optimization (polish)
|
||||
|
||||
Proceed with this plan? (yes/no/modify)
|
||||
```
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
### Benefits of Planning Mode
|
||||
|
||||
1. **Clarity**: Clear roadmap before starting
|
||||
2. **Estimation**: Time and effort estimates
|
||||
3. **Risk Assessment**: Identify potential issues early
|
||||
4. **Prioritization**: Logical order of tasks
|
||||
5. **Approval**: Review and approve before execution
|
||||
6. **Modification**: Adjust plan based on feedback
|
||||
|
||||
### When to Use Planning Mode
|
||||
|
||||
✅ **Always use for**:
|
||||
- Multi-day projects
|
||||
- Team collaborations
|
||||
- Critical system changes
|
||||
- Learning new concepts
|
||||
- Complex refactoring
|
||||
|
||||
❌ **Don't use for**:
|
||||
- Bug fixes
|
||||
- Small tweaks
|
||||
- Simple queries
|
||||
- Quick experiments
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Review plans carefully** before approving
|
||||
2. **Modify plans** when you spot issues
|
||||
3. **Break down** complex tasks
|
||||
4. **Estimate realistic** timeframes
|
||||
5. **Include rollback** strategies
|
||||
6. **Add success** criteria
|
||||
7. **Plan for testing** at each phase
|
||||
265
vi/09-advanced-features/setup-auto-mode-permissions.py
Normal file
265
vi/09-advanced-features/setup-auto-mode-permissions.py
Normal file
@@ -0,0 +1,265 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
setup-auto-mode-permissions.py
|
||||
|
||||
Seed ~/.claude/settings.json with a conservative baseline of safe permissions
|
||||
for Claude Code. The default set is read-only and local-inspection oriented;
|
||||
optional flags let you widen the allowlist for editing, test execution, git
|
||||
write operations, package installs, and GitHub CLI writes.
|
||||
|
||||
Usage:
|
||||
python3 setup-auto-mode-permissions.py
|
||||
python3 setup-auto-mode-permissions.py --dry-run
|
||||
python3 setup-auto-mode-permissions.py --include-edits --include-tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
from typing import Iterable
|
||||
|
||||
SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
|
||||
|
||||
# Core baseline: read-only inspection and low-risk local shell commands.
|
||||
CORE_PERMISSIONS = [
|
||||
"Read(*)",
|
||||
"Glob(*)",
|
||||
"Grep(*)",
|
||||
"Agent(*)",
|
||||
"Skill(*)",
|
||||
"WebSearch(*)",
|
||||
"WebFetch(*)",
|
||||
"Bash(ls:*)",
|
||||
"Bash(pwd:*)",
|
||||
"Bash(which:*)",
|
||||
"Bash(echo:*)",
|
||||
"Bash(cat:*)",
|
||||
"Bash(head:*)",
|
||||
"Bash(tail:*)",
|
||||
"Bash(wc:*)",
|
||||
"Bash(sort:*)",
|
||||
"Bash(uniq:*)",
|
||||
"Bash(find:*)",
|
||||
"Bash(dirname:*)",
|
||||
"Bash(basename:*)",
|
||||
"Bash(realpath:*)",
|
||||
"Bash(file:*)",
|
||||
"Bash(stat:*)",
|
||||
"Bash(diff:*)",
|
||||
"Bash(md5sum:*)",
|
||||
"Bash(sha256sum:*)",
|
||||
"Bash(date:*)",
|
||||
"Bash(env:*)",
|
||||
"Bash(printenv:*)",
|
||||
"Bash(git status:*)",
|
||||
"Bash(git log:*)",
|
||||
"Bash(git diff:*)",
|
||||
"Bash(git branch:*)",
|
||||
"Bash(git show:*)",
|
||||
"Bash(git rev-parse:*)",
|
||||
"Bash(git remote -v:*)",
|
||||
"Bash(git remote get-url:*)",
|
||||
"Bash(git stash list:*)",
|
||||
]
|
||||
|
||||
# Optional but still local: file edits and task bookkeeping.
|
||||
EDITING_PERMISSIONS = [
|
||||
"Edit(*)",
|
||||
"Write(*)",
|
||||
"NotebookEdit(*)",
|
||||
"TaskCreate(*)",
|
||||
"TaskUpdate(*)",
|
||||
]
|
||||
|
||||
# Optional dev/test commands. These can still execute arbitrary project scripts,
|
||||
# so keep them opt-in rather than part of the default baseline.
|
||||
TEST_AND_BUILD_PERMISSIONS = [
|
||||
"Bash(npm test:*)",
|
||||
"Bash(cargo test:*)",
|
||||
"Bash(go test:*)",
|
||||
"Bash(pytest:*)",
|
||||
"Bash(python3 -m pytest:*)",
|
||||
"Bash(make:*)",
|
||||
"Bash(cmake:*)",
|
||||
]
|
||||
|
||||
# Optional local git write operations. History-rewriting commands stay out of
|
||||
# the default baseline because they are easy to misuse.
|
||||
GIT_WRITE_PERMISSIONS = [
|
||||
"Bash(git add:*)",
|
||||
"Bash(git commit:*)",
|
||||
"Bash(git checkout:*)",
|
||||
"Bash(git switch:*)",
|
||||
"Bash(git stash:*)",
|
||||
"Bash(git tag:*)",
|
||||
]
|
||||
|
||||
# Optional dependency/package commands. These are intentionally excluded from
|
||||
# the default baseline because they can execute project hooks or fetch code.
|
||||
PACKAGE_MANAGER_PERMISSIONS = [
|
||||
"Bash(npm ci:*)",
|
||||
"Bash(npm install:*)",
|
||||
"Bash(pip install:*)",
|
||||
"Bash(pip3 install:*)",
|
||||
]
|
||||
|
||||
# Optional GitHub CLI write access.
|
||||
GITHUB_WRITE_PERMISSIONS = [
|
||||
"Bash(gh pr create:*)",
|
||||
]
|
||||
|
||||
# Optional extra GitHub CLI read access.
|
||||
GITHUB_READ_PERMISSIONS = [
|
||||
"Bash(gh pr view:*)",
|
||||
"Bash(gh pr list:*)",
|
||||
"Bash(gh issue view:*)",
|
||||
"Bash(gh issue list:*)",
|
||||
"Bash(gh repo view:*)",
|
||||
]
|
||||
|
||||
|
||||
def parse_args() -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Seed Claude Code settings with a conservative permission baseline."
|
||||
)
|
||||
parser.add_argument(
|
||||
"--dry-run",
|
||||
action="store_true",
|
||||
help="Preview the rules that would be added without writing settings.json",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-edits",
|
||||
action="store_true",
|
||||
help="Add file-editing permissions (Edit/Write/NotebookEdit/TaskCreate/TaskUpdate)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-tests",
|
||||
action="store_true",
|
||||
help="Add local build/test commands such as pytest, cargo test, and make",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-git-write",
|
||||
action="store_true",
|
||||
help="Add local git mutation commands such as add, commit, checkout, and stash",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-packages",
|
||||
action="store_true",
|
||||
help="Add package install commands such as npm ci, npm install, and pip install",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-gh-write",
|
||||
action="store_true",
|
||||
help="Add GitHub CLI write permissions such as gh pr create",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--include-gh-read",
|
||||
action="store_true",
|
||||
help="Add GitHub CLI read permissions such as gh pr view and gh repo view",
|
||||
)
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def load_settings(path: Path) -> dict:
|
||||
if not path.exists():
|
||||
return {}
|
||||
|
||||
try:
|
||||
with path.open() as f:
|
||||
settings = json.load(f)
|
||||
except json.JSONDecodeError as exc:
|
||||
raise SystemExit(f"Invalid JSON in {path}: {exc}") from exc
|
||||
|
||||
if not isinstance(settings, dict):
|
||||
raise SystemExit(f"Expected {path} to contain a JSON object.")
|
||||
|
||||
return settings
|
||||
|
||||
|
||||
def build_permissions(args: argparse.Namespace) -> list[str]:
|
||||
permissions = list(CORE_PERMISSIONS)
|
||||
|
||||
if args.include_edits:
|
||||
permissions.extend(EDITING_PERMISSIONS)
|
||||
|
||||
if args.include_tests:
|
||||
permissions.extend(TEST_AND_BUILD_PERMISSIONS)
|
||||
|
||||
if args.include_git_write:
|
||||
permissions.extend(GIT_WRITE_PERMISSIONS)
|
||||
|
||||
if args.include_packages:
|
||||
permissions.extend(PACKAGE_MANAGER_PERMISSIONS)
|
||||
|
||||
if args.include_gh_write:
|
||||
permissions.extend(GITHUB_WRITE_PERMISSIONS)
|
||||
|
||||
if args.include_gh_read:
|
||||
permissions.extend(GITHUB_READ_PERMISSIONS)
|
||||
|
||||
return permissions
|
||||
|
||||
|
||||
def append_unique(existing: list, new_items: Iterable[str]) -> list[str]:
|
||||
seen = set(existing)
|
||||
added: list[str] = []
|
||||
for item in new_items:
|
||||
if item not in seen:
|
||||
existing.append(item)
|
||||
seen.add(item)
|
||||
added.append(item)
|
||||
return added
|
||||
|
||||
|
||||
def atomic_write_json(path: Path, payload: dict) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
with tempfile.NamedTemporaryFile(
|
||||
"w",
|
||||
encoding="utf-8",
|
||||
dir=str(path.parent),
|
||||
delete=False,
|
||||
) as tmp:
|
||||
json.dump(payload, tmp, indent=2)
|
||||
tmp.write("\n")
|
||||
tmp_path = Path(tmp.name)
|
||||
|
||||
tmp_path.replace(path)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
args = parse_args()
|
||||
permissions_to_add = build_permissions(args)
|
||||
|
||||
settings = load_settings(SETTINGS_PATH)
|
||||
permissions = settings.setdefault("permissions", {})
|
||||
|
||||
if not isinstance(permissions, dict):
|
||||
raise SystemExit("Expected permissions to be a JSON object.")
|
||||
|
||||
allow = permissions.setdefault("allow", [])
|
||||
if not isinstance(allow, list):
|
||||
raise SystemExit("Expected permissions.allow to be a JSON array.")
|
||||
|
||||
added = append_unique(allow, permissions_to_add)
|
||||
|
||||
if not added:
|
||||
print("Nothing to add — all selected rules already present.")
|
||||
return
|
||||
|
||||
print(f"{'Would add' if args.dry_run else 'Adding'} {len(added)} rule(s):")
|
||||
for rule in added:
|
||||
print(f" + {rule}")
|
||||
|
||||
if args.dry_run:
|
||||
print("\nDry run — no changes written.")
|
||||
return
|
||||
|
||||
atomic_write_json(SETTINGS_PATH, settings)
|
||||
print(f"\nDone. {len(added)} rule(s) added to {SETTINGS_PATH}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user