External/context-engineering-intro
1
0
Fork 0
mirror of https://github.com/coleam00/context-engineering-intro.git synced 2025-12-17 09:45:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Finishing up Claude Code guide

Browse Source
This commit is contained in:
Cole Medin 2025-08-05 11:59:18 -05:00
parent 828234dd67
commit 5597e61d36
10 changed files with 877 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
claude-code-full-guide/.claude/agents/documentation-manager.md Normal file
View File

@ -0,0 +1,72 @@
---
name: documentation-manager
description: "Expert documentation specialist. Proactively updates documentation when code changes are made, ensures README accuracy, and maintains comprehensive technical documentation. Be sure to give this subagent information on the files that were changed so it knows where to look to document changes."
tools: Read, Write, Edit, MultiEdit, Grep, Glob, ls
---
You are a documentation management specialist focused on maintaining high-quality, accurate, and comprehensive documentation for software projects. Your primary responsibility is ensuring that all documentation stays synchronized with code changes and remains helpful for developers.
## Core Responsibilities
### 1. Documentation Synchronization
- When code changes are made, proactively check if related documentation needs updates
- Ensure README.md accurately reflects current project state, dependencies, and setup instructions
- Update API documentation when endpoints or interfaces change
- Maintain consistency between code comments and external documentation
### 2. Documentation Structure
- Organize documentation following best practices:
- README.md for project overview and quick start
- docs/ folder for detailed documentation
- API.md for endpoint documentation
- ARCHITECTURE.md for system design
- CONTRIBUTING.md for contribution guidelines
- Ensure clear navigation between documentation files
### 3. Documentation Quality Standards
- Write clear, concise explanations that a mid-level developer can understand
- Include code examples for complex concepts
- Add diagrams or ASCII art where visual representation helps
- Ensure all commands and code snippets are tested and accurate
- Use consistent formatting and markdown conventions
### 4. Proactive Documentation Tasks
When you notice:
- New features added → Update feature documentation
- Dependencies changed → Update installation/setup docs
- API changes → Update API documentation and examples
- Configuration changes → Update configuration guides
- Breaking changes → Add migration guides
### 5. Documentation Validation
- Check that all links in documentation are valid
- Verify that code examples compile/run correctly
- Ensure setup instructions work on fresh installations
- Validate that documented commands produce expected results
## Working Process
1. **Analyze Changes**: When code modifications occur, analyze what was changed
2. **Identify Impact**: Determine which documentation might be affected
3. **Update Systematically**: Update all affected documentation files
4. **Validate Changes**: Ensure documentation remains accurate and helpful
5. **Cross-Reference**: Make sure all related docs are consistent
## Key Principles
- Documentation is as important as code
- Out-of-date documentation is worse than no documentation
- Examples are worth a thousand words
- Always consider the reader's perspective
- Test everything you document
## Output Standards
When updating documentation:
- Use clear headings and subheadings
- Include table of contents for long documents
- Add timestamps or version numbers when relevant
- Provide both simple and advanced examples
- Link to related documentation sections
Remember: Good documentation reduces support burden, accelerates onboarding, and makes projects more maintainable. Always strive for clarity, accuracy, and completeness.

133
claude-code-full-guide/.claude/agents/validation-gates.md Normal file
View File

@ -0,0 +1,133 @@
---
name: validation-gates
description: "Testing and validation specialist. Proactively runs tests, validates code changes, ensures quality gates are met, and iterates on fixes until all tests pass. Call this agent after you implement features and need to validate that they were implemented correctly. Be very specific with the features that were implemented and a general idea of what needs to be tested."
tools: Bash, Read, Edit, MultiEdit, Grep, Glob, TodoWrite
---
You are a validation and testing specialist responsible for ensuring code quality through comprehensive testing, validation, and iterative improvement. Your role is to act as a quality gatekeeper, ensuring that all code changes meet the project's standards before being considered complete.
## Core Responsibilities
### 1. Automated Testing Execution
- Run all relevant tests after code changes
- Execute linting and formatting checks
- Run type checking where applicable
- Perform build validation
- Check for security vulnerabilities
### 2. Test Coverage Management
- Ensure new code has appropriate test coverage
- Write missing tests for uncovered code paths
- Validate that tests actually test meaningful scenarios
- Maintain or improve overall test coverage metrics
### 3. Iterative Fix Process
When tests fail:
1. Analyze the failure carefully
2. Identify the root cause
3. Implement a fix
4. Re-run tests to verify the fix
5. Continue iterating until all tests pass
6. Document any non-obvious fixes
### 4. Validation Gates Checklist
Before marking any task as complete, ensure:
- [ ] All unit tests pass
- [ ] Integration tests pass (if applicable)
- [ ] Linting produces no errors
- [ ] Type checking passes (for typed languages)
- [ ] Code formatting is correct
- [ ] Build succeeds without warnings
- [ ] No security vulnerabilities detected
- [ ] Performance benchmarks met (if applicable)
### 5. Test Writing Standards
When creating new tests:
- Write descriptive test names that explain what is being tested
- Include at least:
- Happy path test cases
- Edge case scenarios
- Error/failure cases
- Boundary condition tests
- Use appropriate testing patterns (AAA: Arrange, Act, Assert)
- Mock external dependencies appropriately
- Keep tests fast and deterministic
## Validation Process Workflow
1. **Initial Assessment**
- Identify what type of validation is needed
- Determine which tests should be run
- Check for existing test suites
2. **Execute Validation**
```bash
# Example validation sequence (adapt based on project)
npm run lint
npm run typecheck
npm run test
npm run build
```
3. **Handle Failures**
- Read error messages carefully
- Use grep/search to find related code
- Fix issues one at a time
- Re-run failed tests after each fix
4. **Iterate Until Success**
- Continue fixing and testing
- Don't give up after first attempt
- Try different approaches if needed
- Ask for help if truly blocked
5. **Final Verification**
- Run complete test suite one final time
- Verify no regressions were introduced
- Ensure all validation gates pass
## Common Validation Commands by Language
### JavaScript/TypeScript
```bash
npm run lint # or: npx eslint .
npm run typecheck # or: npx tsc --noEmit
npm run test # or: npx jest
npm run test:coverage # Check coverage
npm run build # Verify build
```
### Python
```bash
ruff check . # Linting
mypy . # Type checking
pytest # Run tests
pytest --cov # With coverage
python -m build # Build check
```
### Go
```bash
go fmt ./... # Format
go vet ./... # Linting
go test ./... # Run tests
go build . # Build validation
```
## Quality Metrics to Track
- Test success rate (must be 100%)
- Code coverage (aim for >80%)
- Linting warnings/errors (should be 0)
- Build time (shouldn't increase significantly)
- Test execution time (keep under reasonable limits)
## Important Principles
1. **Never Skip Validation**: Even for "simple" changes
2. **Fix, Don't Disable**: Fix failing tests rather than disabling them
3. **Test Behavior, Not Implementation**: Focus on what code does, not how
4. **Fast Feedback**: Run quick tests first, comprehensive tests after
5. **Document Failures**: When tests reveal bugs, document the fix
Remember: Your role is to ensure that code not only works but is maintainable, reliable, and meets all quality standards. Be thorough, be persistent, and don't compromise on quality.

16
claude-code-full-guide/.claude/commands/primer.md Normal file
View File

@ -0,0 +1,16 @@
# Prime Context for Claude Code
Use the command `tree` to get an understanding of the project structure.
Start with reading the CLAUDE.md file if it exists to get an understanding of the project.
Read the README.md file to get an understanding of the project.
Read key files in the src/ or root directory
Explain back to me:
- Project structure
- Project purpose and goals
- Key files and their purposes
- Any important dependencies
- Any important configuration files

109
claude-code-full-guide/.claude/hooks/README.md Normal file
View File

@ -0,0 +1,109 @@
# Claude Code Hooks Examples
This directory contains example hooks for Claude Code that demonstrate how to add deterministic behavior to your AI coding workflow.
## What are Hooks?
Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide control over Claude's behavior, ensuring certain actions always happen rather than relying on the AI to choose to run them.
## Files in this Directory
1. **format-after-edit.sh** - A PostToolUse hook that automatically formats code after file edits
2. **example-hook-config.json** - Example configuration showing how to set up various hooks
## How to Use These Hooks
### Option 1: Copy to Your Settings File
Copy the hooks configuration from `example-hook-config.json` to your Claude Code settings:
**Project-specific** (`.claude/settings.json`):
```bash
# Create settings file if it doesn't exist
touch .claude/settings.json
# Add hooks configuration from example-hook-config.json
```
**User-wide** (`~/.claude/settings.json`):
```bash
# Apply hooks to all Claude Code sessions
cp example-hook-config.json ~/.claude/settings.json
```
### Option 2: Use Individual Hooks
1. Copy the hook script to your project:
```bash
cp format-after-edit.sh /your/project/.claude/hooks/
chmod +x /your/project/.claude/hooks/format-after-edit.sh
```
2. Add to your settings.json:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/format-after-edit.sh"
}
]
}
]
}
}
```
## Available Hook Events
- **PreToolUse**: Before tool execution (can block tools)
- **PostToolUse**: After successful tool completion
- **UserPromptSubmit**: When user submits a prompt
- **SubagentStop**: When a subagent completes
- **Stop**: When main agent finishes responding
- **Notification**: During system notifications
- **PreCompact**: Before context compaction
- **SessionStart**: At session initialization
## Creating Your Own Hooks
1. Write a shell script that:
- Reads JSON input from stdin
- Processes the input
- Returns JSON output (empty `{}` for success)
- Can return `{"action": "block", "message": "reason"}` to block operations
2. Make it executable:
```bash
chmod +x your-hook.sh
```
3. Add to settings.json with appropriate matcher and event
## Security Considerations
- Hooks execute arbitrary shell commands
- Always validate and sanitize inputs
- Use full paths to avoid PATH manipulation
- Be careful with file operations
- Test hooks thoroughly before deployment
## Debugging Hooks
Run Claude Code with debug flag to see hook execution:
```bash
claude --debug
```
This will show:
- Which hooks are triggered
- Input/output for each hook
- Any errors or issues
## Integration with Subagents
The example configuration includes a hook that integrates with the validation-gates subagent, demonstrating how hooks and subagents can work together for a more robust development workflow.

50
claude-code-full-guide/.claude/hooks/example-hook-config.json Normal file
View File

@ -0,0 +1,50 @@
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/format-after-edit.sh",
"description": "Automatically format code after file edits"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash -c 'input=$(cat); cmd=$(echo \"$input\" | jq -r \".tool_input.command // empty\"); if [[ \"$cmd\" =~ (rm|delete).*(\\*|\\.env|credentials|secret) ]]; then echo \"{\\\"action\\\": \\\"block\\\", \\\"message\\\": \\\"Dangerous command blocked: $cmd\\\"}\"; else echo \"{}\"; fi'",
"description": "Block dangerous bash commands"
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'input=$(cat); agent=$(echo \"$input\" | jq -r \".subagent_name // empty\"); if [[ \"$agent\" == \"validation-gates\" ]]; then echo \"Validation gates completed. Running final checks...\" >&2; fi; echo \"{}\"'",
"description": "Log when validation-gates subagent completes"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "bash -c 'input=$(cat); prompt=$(echo \"$input\" | jq -r \".prompt // empty\"); if [[ \"$prompt\" =~ (test|validate|check) ]] && [[ ! \"$prompt\" =~ (skip|no|without).*(test|validation) ]]; then echo \"Reminder: Use the validation-gates subagent to ensure comprehensive testing.\" >&2; fi; echo \"{}\"'",
"description": "Remind about validation when testing is mentioned"
}
]
}
]
}
}

70
claude-code-full-guide/.claude/hooks/format-after-edit.sh Normal file
View File

@ -0,0 +1,70 @@
#!/bin/bash
# PostToolUse hook: Automatically format code after file edits
# This hook runs after Edit, Write, or MultiEdit tools to ensure consistent formatting
# Read the JSON input from stdin
input=$(cat)
# Extract tool name and file path from the input
tool_name=$(echo "$input" | jq -r '.tool_name // empty')
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
# Only process if it's a file editing tool and we have a file path
if [[ "$tool_name" =~ ^(Edit|Write|MultiEdit)$ ]] && [[ -n "$file_path" ]]; then
# Determine file extension
extension="${file_path##*.}"
# Format based on file type
case "$extension" in
js|jsx|ts|tsx)
# JavaScript/TypeScript files
if command -v prettier &> /dev/null; then
echo "Formatting $file_path with Prettier..." >&2
prettier --write "$file_path" 2>/dev/null || true
elif command -v npx &> /dev/null; then
echo "Formatting $file_path with npx prettier..." >&2
npx prettier --write "$file_path" 2>/dev/null || true
fi
;;
py)
# Python files
if command -v black &> /dev/null; then
echo "Formatting $file_path with Black..." >&2
black "$file_path" 2>/dev/null || true
elif command -v ruff &> /dev/null; then
echo "Formatting $file_path with Ruff..." >&2
ruff format "$file_path" 2>/dev/null || true
fi
;;
go)
# Go files
if command -v gofmt &> /dev/null; then
echo "Formatting $file_path with gofmt..." >&2
gofmt -w "$file_path" 2>/dev/null || true
fi
;;
rs)
# Rust files
if command -v rustfmt &> /dev/null; then
echo "Formatting $file_path with rustfmt..." >&2
rustfmt "$file_path" 2>/dev/null || true
fi
;;
json)
# JSON files
if command -v jq &> /dev/null; then
echo "Formatting $file_path with jq..." >&2
# Format JSON with jq (careful with large files)
if [[ $(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null) -lt 1048576 ]]; then
jq . "$file_path" > "$file_path.tmp" && mv "$file_path.tmp" "$file_path" 2>/dev/null || true
fi
fi
;;
esac
# Log formatting completion
echo "Post-edit formatting completed for $file_path" >&2
fi
# Always return success to avoid blocking the tool
echo "{}"

25
claude-code-full-guide/.claude/hooks/log-tool-usage.sh Normal file
View File

@ -0,0 +1,25 @@
#!/bin/bash
# PostToolUse hook: Log all tool usage for tracking and debugging
# This hook runs after any tool execution to maintain an audit log
# Read the JSON input from stdin
input=$(cat)
# Extract tool name and basic info
tool_name=$(echo "$input" | jq -r '.tool_name // "unknown"')
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
# Create logs directory if it doesn't exist
mkdir -p .claude/logs
# Log the tool usage
echo "[$timestamp] Tool used: $tool_name" >> .claude/logs/tool-usage.log
# Optionally, you can add more detailed logging
if [[ "$tool_name" =~ ^(Edit|Write|MultiEdit)$ ]]; then
file_path=$(echo "$input" | jq -r '.tool_input.file_path // "unknown"')
echo "[$timestamp] File operation: $tool_name on $file_path" >> .claude/logs/file-operations.log
fi
# Always return success to avoid blocking tools
echo "{}"

5
claude-code-full-guide/.claude/settings.local.json
View File

@ -10,6 +10,7 @@
"Bash(tree:*)", "Bash(tree:*)",
"Bash(ruff:*)", "Bash(ruff:*)",
"Bash(touch:*)", "Bash(touch:*)",
"Bash(chmod:*)",
"Bash(cat:*)", "Bash(cat:*)",
"Bash(ruff check:*)", "Bash(ruff check:*)",
"Bash(pytest:*)", "Bash(pytest:*)",
@ -18,9 +19,7 @@
"Bash(python3 -m pytest:*)", "Bash(python3 -m pytest:*)",
"WebFetch(domain:*)", "WebFetch(domain:*)",
"Bash(gh issue view:*)", "Bash(gh issue view:*)",
"mcp__puppeteer__puppeteer_navigate", "WebFetch(domain:docs.anthropic.com)"
"mcp__puppeteer__puppeteer_screenshot",
"mcp__puppeteer__puppeteer_evaluate"
], ],
"deny": [] "deny": []
} }

588
claude-code-full-guide/README.md
View File

@ -1,6 +1,6 @@
# 🚀 Full Guide to Using Claude Code # 🚀 Full Guide to Using Claude Code
Everything you need to know to crush building anything with Claude Code! This guide takes you from installation through advanced context engineering and parallel agent workflows. Everything you need to know to crush building anything with Claude Code! This guide takes you from installation through advanced context engineering, subagents, hooks, and parallel agent workflows.
## 📋 Prerequisites ## 📋 Prerequisites
@ -17,7 +17,7 @@ npm install -g @anthropic-ai/claude-code
``` ```
**Windows (WSL recommended):** **Windows (WSL recommended):**
See detailed instructions in [install_claude_code_windows.md](../git-and-claude-code/install_claude_code_windows.md) See detailed instructions in [install_claude_code_windows.md](./install_claude_code_windows.md)
**Verify installation:** **Verify installation:**
```bash ```bash
@ -40,7 +40,7 @@ Use the built-in command:
/init /init
``` ```
Or create your own CLAUDE.md file based on the template in this repository. See `CLAUDE.md` for an example structure that includes: Or create your own CLAUDE.md file based on the template in this repository. See `CLAUDE.md` for a Python specific example structure that includes:
- Project awareness and context rules - Project awareness and context rules
- Code structure guidelines - Code structure guidelines
- Testing requirements - Testing requirements
@ -48,6 +48,19 @@ Or create your own CLAUDE.md file based on the template in this repository. See
- Style conventions - Style conventions
- Documentation standards - Documentation standards
### Advanced Prompting Techniques
**Power Keywords**: Claude responds to certain keywords with enhanced behavior (information dense keywords):
- **IMPORTANT**: Emphasizes critical instructions that should not be overlooked
- **Proactively**: Encourages Claude to take initiative and suggest improvements
- **Ultra-think**: Can trigger more thorough analysis (use sparingly)
**Essential Prompt Engineering Tips**:
- Avoid prompting for "production-ready" code - this often leads to over-engineering
- Prompt Claude to write scripts to check its work: "After implementing, create a validation script"
- Avoid backward compatibility unless specifically needed - Claude tends to preserve old code unnecessarily
- Focus on clarity and specific requirements rather than vague quality descriptors
### File Placement Strategies ### File Placement Strategies
Claude automatically reads CLAUDE.md files from multiple locations: Claude automatically reads CLAUDE.md files from multiple locations:
@ -62,18 +75,16 @@ root/CLAUDE.md # General project info
root/frontend/CLAUDE.md # Frontend-specific context root/frontend/CLAUDE.md # Frontend-specific context
root/backend/CLAUDE.md # Backend-specific context root/backend/CLAUDE.md # Backend-specific context
# Home folder (applies to all sessions) # Reference external files for flexibility
~/.claude/CLAUDE.md # Personal preferences and global settings echo "Follow best practices in: ~/company/engineering-standards.md" > CLAUDE.md
# Child directories (pulled on demand)
root/components/CLAUDE.md # Component-specific guidelines
root/utils/CLAUDE.md # Utility function patterns
``` ```
Claude reads files in this order: **Pro Tip**: Many teams keep their CLAUDE.md minimal and reference a shared standards document. This makes it easy to:
1. Current directory - Switch between AI coding assistants
2. Parent directories (up to repository root) - Update standards without changing every project
3. Home directory ~/.claude/ - Share best practices across teams
*Note: While Claude Code reads CLAUDE.md automatically, other AI coding assistants can use similar context files (such as .cursorrules for Cursor)*
--- ---
@ -92,6 +103,8 @@ Then add:
- `Edit` (for file edits) - `Edit` (for file edits)
- `Bash(git commit:*)` (for git commits) - `Bash(git commit:*)` (for git commits)
- `Bash(npm:*)` (for npm commands) - `Bash(npm:*)` (for npm commands)
- `Read` (for reading files)
- `Write` (for creating files)
**Method 3: Create project settings file** **Method 3: Create project settings file**
Create `.claude/settings.local.json`: Create `.claude/settings.local.json`:
@ -99,295 +112,423 @@ Create `.claude/settings.local.json`:
{ {
"allowedTools": [ "allowedTools": [
"Edit", "Edit",
"Read",
"Write",
"Bash(git add:*)", "Bash(git add:*)",
"Bash(git commit:*)", "Bash(git commit:*)",
"Bash(npm:*)" "Bash(npm:*)",
"Bash(python:*)",
"Bash(pytest:*)"
] ]
} }
``` ```
--- **Security Best Practices**:
- Never allow `Bash(rm -rf:*)` or similar destructive commands
- Use specific command patterns rather than `Bash(*)`
- Review permissions regularly
- Use different permission sets for different projects
## ✅ TIP 3: INSTALL AND CONFIGURE GITHUB CLI *Note: All AI coding assistants have permission management - some built-in, others require manual approval for each action.*
Set up the GitHub CLI to enable Claude to interact with GitHub for issues, pull requests, and repository management.
```bash
# Install GitHub CLI (if not already installed)
# Visit: https://github.com/cli/cli?tab=readme-ov-file#installation
# On Linux or Windows in WSL, see: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
# Authenticate
gh auth login # WSL - you'll have to copy the URL and visit it manually
# Verify setup
gh repo list
```
Claude can now use commands like:
- `gh issue create`
- `gh pr create`
- `gh pr merge`
- `gh issue list`
- `gh repo clone`
**Custom GitHub Issue Fix Command:**
Use the custom fix-github-issue slash command to automatically analyze and fix GitHub issues:
```bash
/fix-github-issue 1
```
This command will:
1. Fetch issue details using `gh issue view`
2. Analyze the problem and search relevant code
3. Implement the fix with proper testing
4. Create a commit and pull request
--- ---
## ✅ TIP 4: SAFE YOLO MODE WITH DEV CONTAINERS ## ✅ TIP 3: MASTER CUSTOM SLASH COMMANDS
Allow Claude Code to perform any action while maintaining safety through containerization. This enables rapid development without destructive behavior on your host machine. Anthropic documentation for this is [here](https://docs.anthropic.com/en/docs/claude-code/dev-container). Slash commands are the key to adding your own workflows into Claude Code. They live in `.claude/commands/` and enable you to create reusable, parameterized workflows.
**Prerequisites:** ### Built-in Commands
- Install [Docker](https://www.docker.com/) and VS Code (or a VS Code fork like Windsurf/Cursor) - `/init` - Generate initial CLAUDE.md
- `/permissions` - Manage tool permissions
- `/clear` - Clear context between tasks
- `/agents` - Manage subagents
- `/help` - Get help with Claude Code
**🛡️ Security Features:** ### Custom Command Example
The dev container in this repository provides:
- **Network isolation**: Custom firewall restricts outbound connections to whitelisted domains only
- **Essential tools**: Pre-installed with Claude Code, GitHub CLI, and development tools
- **Secure environment**: Built on Node.js 20 with ZSH and developer-friendly tools
**Setup Process:** **Repository Analysis**:
```
/primer
```
Performs comprehensive repository analysis to prime Claude Code on your codebase so you can start implemention fixes or new features and it has all the necessary context to do so.
1. **Open project in VS Code** ### Creating Your Own Commands
2. **Activate the dev container:**
- Press `F1` or `Ctrl/Cmd + Shift + P` to open Command Palette
- Type and select "Dev Containers: Reopen in Container"
- OR click the blue button in bottom-left corner → "Reopen in Container"
3. **Wait for container to build** (first time takes a few minutes)
4. **Open a new termainl** - Ctrl + J or Terminal → New Terminal
5. **Authenticate with Claude Code** - You'll have to set up Claude Code and authenticate again in the container
6. **Run Claude in YOLO mode:**
```bash
claude --dangerously-skip-permissions
```
Note - when you authenticate with Claude Code in the container, copy the auth URL and go to it manually in your browser instead of having it open the link automatically. That won't work since you're in the container! 1. Create a markdown file in `.claude/commands/`:
```markdown
# Command: analyze-performance
**Configuration Details:** Analyze the performance of the file specified in $ARGUMENTS.
The `.devcontainer/` folder contains:
- `devcontainer.json`: VS Code container configuration with extensions and settings
- `Dockerfile`: Container image with Node.js 20, development tools, and Claude Code pre-installed
- `init-firewall.sh`: Security script that allows only necessary domains (GitHub, Anthropic API, npm registry)
This setup enables rapid prototyping while preventing access to unauthorized external services. ## Steps:
1. Read the file at path: $ARGUMENTS
2. Identify performance bottlenecks
3. Suggest optimizations
4. Create a benchmark script
```
2. Use the command:
```
/analyze-performance src/heavy-computation.js
```
Commands can use `$ARGUMENTS` to receive parameters and can invoke any of Claude's tools.
*Note: Other AI coding assistants can use these commands as regular prompts - just copy the command content and paste it with your arguments.*
--- ---
## ✅ TIP 5: INTEGRATE MCP SERVERS ## ✅ TIP 4: INTEGRATE MCP SERVERS
Connect Claude Code to Model Context Protocol (MCP) servers for enhanced functionality like browser automation and database management. Learn more in the [MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp). Connect Claude Code to Model Context Protocol (MCP) servers for enhanced functionality. Learn more in the [MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).
**Add MCP servers:** **Add Serena MCP Server** - The most powerful coding toolkit:
Make sure you [install uvx](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) first. Here is how you do that in WSL with Windows:
```bash ```bash
# Stdio server (real example) sudo snap install astral-uv --classic
claude mcp add puppeteer npx @modelcontextprotocol/server-puppeteer
# SSE server (add your own server)
claude mcp add --transport sse myserver https://example.com/sse
# HTTP server (add your own server)
claude mcp add --transport http myserver https://example.com/api
``` ```
For Puppeteer, also run the command to install necessary dependencies: Then add Serena using the command:
```bash ```bash
sudo apt-get install -y libnss3-dev libxss1 libxtst6 libxrandr2 libasound2t64 libpangocairo-1.0-0 libatk1.0-0t64 libcairo-gobject2 libgtk-3-0t64 libgdk-pixbuf2.0-0 # Install Serena for semantic code analysis and editing
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
``` ```
[Serena](https://github.com/oraios/serena) transforms Claude Code into a fully-featured coding agent with:
- Semantic code retrieval and analysis
- Advanced editing capabilities using Language Server Protocol (LSP)
- Support for Python, TypeScript/JavaScript, PHP, Go, Rust, C/C++, Java
- Free and open-source alternative to subscription-based coding assistants
**Manage MCP servers:** **Manage MCP servers:**
```bash ```bash
# List all configured servers # List all configured servers
claude mcp list claude mcp list
# Get details about a specific server # Get details about a specific server
claude mcp get puppeteer claude mcp get serena
# Remove a server # Remove a server
claude mcp remove puppeteer claude mcp remove serena
``` ```
**Test MCP integration:** **Coming Soon**: Archon V2 (HUGE Overhaul) - A comprehensive knowledge and task management backbone for AI coding assistants - enabling true human-AI collaboration on code for the first time.
> "Use puppeteer to visit https://docs.anthropic.com/en/docs/claude-code/hooks and get me a high level overview of Claude Code Hooks."
**Configuration scopes:** *Note: MCP is integrated with every major AI coding assistant and the servers are managed in a very similar way.*
- **Local**: Project-specific, private configuration
- **Project**: Shared via `.mcp.json`, team collaboration
- **User**: Available across all projects (`~/.claude/mcp.json`)
**Popular MCP servers:**
- **Puppeteer**: Browser automation and screenshots
- **Supabase**: Database management and real-time features
- **Neon**: Serverless PostgreSQL database operations
- **Sentry**: Error monitoring and performance tracking
- **Slack**: Team communication and notifications
- **Archon**: AI agent builder framework ([coming soon](https://github.com/coleam00/Archon))
**Advanced features:**
- Reference MCP resources using `@` mentions in your prompts
- Execute MCP prompts as slash commands
- OAuth 2.0 support for remote servers
--- ---
## ✅ TIP 6: CONTEXT ENGINEERING ## ✅ TIP 5: CONTEXT ENGINEERING WITH EXAMPLES
Transform your development workflow from simple prompting to comprehensive context engineering - providing AI with all the information needed for end-to-end implementation. Transform your development workflow from simple prompting to comprehensive context engineering - providing AI with all the information needed for end-to-end implementation.
*Note: While your initial feature request is usually a comprehensive document outlining what you want, we provide a simpler template here to get started.*
### Quick Start ### Quick Start
```bash The PRP (Product Requirements Prompt) framework is a simple 3-step strategy for context engineering:
# 1. Use the provided template for your feature request
# Edit INITIAL.md (or copy INITIAL_EXAMPLE.md as a starting point)
# 2. Generate a comprehensive PRP (Product Requirements Prompt) ```bash
# 1. Define your requirements with examples and context
# Edit INITIAL.md to include example code and patterns
# 2. Generate a comprehensive PRP
/generate-prp INITIAL.md /generate-prp INITIAL.md
# 3. Execute the PRP to implement your feature # 3. Execute the PRP to implement your feature
/execute-prp PRPs/your-feature-name.md /execute-prp PRPs/your-feature-name.md
``` ```
### The Context Engineering Workflow ### Defining Your Requirements
**1. Create Your Initial Feature Request** Your INITIAL.md should always include:
Use `INITIAL_EXAMPLE.md` as a template. The INITIAL.md file should contain:
- **FEATURE**: Specific description of what you want to build
- **EXAMPLES**: References to example files showing patterns to follow
- **DOCUMENTATION**: Links to relevant docs, APIs, or resources
- **OTHER CONSIDERATIONS**: Important details, gotchas, requirements
**2. Generate the PRP** ```markdown
The `/generate-prp` command will: ## FEATURE
- Research your codebase for patterns Build a user authentication system
- Search for relevant documentation
- Create a comprehensive blueprint in `PRPs/` folder
- Include validation gates and test requirements
**3. Execute the PRP** ## EXAMPLES
The `/execute-prp` command will: - Authentication flow: `examples/auth-flow.js`
- Read all context from the PRP - Similar API endpoint: `src/api/users.js`
- Create a detailed task list using TodoWrite - Database schema pattern: `src/models/base-model.js`
- Implement each component with validation - Validation approach: `src/validators/user-validator.js`
- Run tests and fix any issues
- Ensure all requirements are met
### Custom Slash Commands ## DOCUMENTATION
- JWT library docs: https://github.com/auth0/node-jsonwebtoken
- Our API standards: `docs/api-guidelines.md`
The `.claude/commands/` folder contains reusable workflows: ## OTHER CONSIDERATIONS
- `generate-prp.md` - Researches and creates comprehensive PRPs - Use existing error handling patterns
- `execute-prp.md` - Implements features from PRPs - Follow our standard response format
- Include rate limiting
```
These commands use the `$ARGUMENTS` variable to receive whatever you pass after the command name. ### Critical PRP Strategies
**Examples**: The most powerful tool - provide code snippets, similar features, and patterns to follow
**Validation Gates**: Ensure comprehensive testing and iteration until all tests pass
**No Vibe Coding**: Validate PRPs before executing them and the code after execution!
The more specific examples you provide, the better Claude can match your existing patterns and style.
*Note: Context engineering works with any AI coding assistant - the PRP framework and example-driven approach are universal principles.*
--- ---
## ✅ TIP 7: PARALLEL DEVELOPMENT WITH GIT WORKTREES ## ✅ TIP 6: LEVERAGE SUBAGENTS FOR SPECIALIZED TASKS
Use Git worktrees to enable multiple Claude instances working on independent tasks simultaneously without conflicts. Subagents are specialized AI assistants that operate in separate context windows with focused expertise. They enable Claude to delegate specific tasks to experts, improving quality and efficiency.
### Understanding Subagents
Each subagent:
- Has its own context window (no pollution from main conversation)
- Operates with specialized system prompts
- Can be limited to specific tools
- Works autonomously on delegated tasks
### Example Subagents in This Repository
**Documentation Manager** (`.claude/agents/documentation-manager.md`):
- Automatically updates docs when code changes
- Ensures README accuracy
- Maintains API documentation
- Creates migration guides
**Validation Gates** (`.claude/agents/validation-gates.md`):
- Runs all tests after changes
- Iterates on fixes until tests pass
- Enforces code quality standards
- Never marks tasks complete with failing tests
### Creating Your Own Subagents
1. Use the `/agents` command or create a file in `.claude/agents/`:
```markdown
---
name: security-auditor
description: "Security specialist. Proactively reviews code for vulnerabilities and suggests improvements."
tools: Read, Grep, Glob
---
You are a security auditing specialist focused on identifying and preventing security vulnerabilities...
## Core Responsibilities
1. Review code for OWASP Top 10 vulnerabilities
2. Check for exposed secrets or credentials
3. Validate input sanitization
4. Ensure proper authentication/authorization
...
```
### Subagent Best Practices
**1. Focused Expertise**: Each subagent should have one clear specialty
**2. Proactive Descriptions**: Use "proactively" in descriptions for automatic invocation:
```yaml
description: "Code reviewer. Proactively reviews all code changes for quality."
```
**3. Tool Limitations**: Only give subagents the tools they need:
```yaml
tools: Read, Grep # No write access for review-only agents
```
**4. Information Flow Design**: Understand how information flows from primary agent → subagent → primary agent. The subagent description is crucial because it tells your primary Claude Code agent when and how to use it. Include clear instructions in the description for how the primary agent should prompt this subagent.
**5. One-Shot Context**: Subagents don't have full conversation history - they receive a single prompt from your primary agent. Design your subagents with this limitation in mind.
Learn more in the [Subagents documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents).
*Note: While other AI assistants don't have formal subagents, you can achieve similar results by creating specialized prompts and switching between different conversation contexts.*
---
## ✅ TIP 7: AUTOMATE WITH HOOKS
Hooks provide deterministic control over Claude Code's behavior through user-defined shell commands that execute at predefined lifecycle events.
### Available Hook Events
Claude Code provides several predefined actions you can hook into:
- **PreToolUse**: Before tool execution (can block operations)
- **PostToolUse**: After successful tool completion
- **UserPromptSubmit**: When user submits a prompt
- **SubagentStop**: When a subagent completes its task
- **Stop**: When the main agent finishes responding
- **SessionStart**: At session initialization
- **PreCompact**: Before context compaction
- **Notification**: During system notifications
Learn more in the [Hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks).
### Example Hook: Tool Usage Logging
This repository includes a simple hook example in `.claude/hooks/`:
**log-tool-usage.sh** - Logs all tool usage for tracking and debugging:
```bash
#!/bin/bash
# Logs tool usage with timestamps
# Creates .claude/logs/tool-usage.log
# No external dependencies required
```
### Setting Up Hooks
1. **Create hook script** in `.claude/hooks/`
2. **Make it executable**: `chmod +x your-hook.sh`
3. **Add to settings** in `.claude/settings.json`:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/log-tool-usage.sh"
}
]
}
]
}
}
```
Hooks ensure certain actions always happen, rather than relying on the AI to remember - perfect for logging, security validations, and build triggers.
*Note: Other AI assistants don't have hooks (though Kiro does!), I can almost guarantee they're coming soon for everyone else.*
---
## ✅ TIP 8: GITHUB CLI INTEGRATION
Set up the GitHub CLI to enable Claude to interact with GitHub for issues, pull requests, and repository management.
```bash
# Install GitHub CLI
# Visit: https://github.com/cli/cli#installation
# Authenticate
gh auth login
# Verify setup
gh repo list
```
### Custom GitHub Commands
Use the `/fix-github-issue` command for automated fixes:
```
/fix-github-issue 123
```
This will:
1. Fetch issue details
2. Analyze the problem
3. Search relevant code
4. Implement the fix
5. Run tests
6. Create a PR
*Note: GitHub CLI works with any AI coding assistant - just install it and the AI can use `gh` commands to interact with your repositories.*
---
## ✅ TIP 9: SAFE YOLO MODE WITH DEV CONTAINERS
Allow Claude Code to perform any action while maintaining safety through containerization. This enables rapid development without destructive behavior on your host machine.
**Prerequisites:**
- Install [Docker](https://www.docker.com/)
- VS Code (or compatible editors)
**Security Features:**
- Network isolation with whitelist
- No access to host filesystem
- Restricted outbound connections
- Safe experimentation environment
**Setup Process:**
1. **Open in VS Code** and press `F1`
2. **Select** "Dev Containers: Reopen in Container"
3. **Wait** for container build
4. **Open terminal** (`Ctrl+J`)
5. **Authenticate** Claude Code in container
6. **Run in YOLO mode**:
```bash
claude --dangerously-skip-permissions
```
**Why Use Dev Containers?**
- Test dangerous operations safely
- Experiment with system changes
- Rapid prototyping
- Consistent development environment
- No fear of breaking your system
---
## ✅ TIP 10: PARALLEL DEVELOPMENT WITH GIT WORKTREES
Use Git worktrees to enable multiple Claude instances working on independent tasks simultaneously, or automate parallel implementations of the same feature.
### Manual Worktree Setup ### Manual Worktree Setup
```bash ```bash
# Create worktrees for different features # Create worktrees for different features
git worktree add ../project-feature-a feature-a git worktree add ../project-auth feature/auth
git worktree add ../project-feature-b feature-b git worktree add ../project-api feature/api
# Launch Claude in each worktree # Launch Claude in each worktree
cd ../project-feature-a && claude # Terminal tab 1 cd ../project-auth && claude # Terminal 1
cd ../project-feature-b && claude # Terminal tab 2 cd ../project-api && claude # Terminal 2
``` ```
**Benefits:** ### Automated Parallel Agents
- Independent tasks don't interfere
- No merge conflicts during development
- Isolated file systems for each task
- Share same Git history
**Cleanup when finished:** AI coding assistants are non-deterministic. Running multiple attempts increases success probability and provides implementation options.
**Setup parallel worktrees:**
```bash ```bash
git worktree remove ../project-feature-a /prep-parallel user-system 3
git branch -d feature-a
``` ```
--- **Execute parallel implementations:**
1. Create a plan file (`plan.md`)
## ✅ TIP 8: AUTOMATED PARALLEL CODING AGENTS 2. Run parallel execution:
Use automated commands to spin up multiple agents working on the same feature in parallel, then pick the best implementation.
### Setup Parallel Worktrees
```bash ```bash
/prep-parallel simple-cli 3 /execute-parallel user-system plan.md 3
``` ```
This creates three folders: **Select the best implementation:**
- `trees/simple-cli-1`
- `trees/simple-cli-2`
- `trees/simple-cli-3`
### Execute Parallel Implementations
1. Create a plan file (e.g., `plan.md`) describing the feature
2. Execute the parallel agents:
```bash ```bash
/execute-parallel simple-cli plan.md 3 # Review results
``` cat trees/user-system-*/RESULTS.md
Claude Code will: # Test each implementation
- Kick off multiple agents in parallel cd trees/user-system-1 && npm test
- Each tackles the same feature independently
- Different implementations due to LLM non-determinism
- Each saves results in `RESULTS.md` in their workspace
**Why this works:** # Merge the best
AI coding assistants make mistakes, so multiple attempts increase chances of success. You can review all implementations and merge the best one.
### Merge the Best Implementation
After reviewing the different implementations:
1. **Choose the best implementation:**
```bash
# Review each result
cat trees/simple-cli-1/RESULTS.md
cat trees/simple-cli-2/RESULTS.md
cat trees/simple-cli-3/RESULTS.md
```
2. **Merge the selected branch:**
```bash
# If you chose implementation #2
git checkout main git checkout main
git merge simple-cli-2 git merge user-system-2
git push origin main
``` ```
3. **Clean up all worktrees:** ### Benefits
```bash
git worktree remove trees/simple-cli-1 - **No Conflicts**: Each instance works in isolation
git worktree remove trees/simple-cli-2 - **Multiple Approaches**: Compare different implementations
git worktree remove trees/simple-cli-3 - **Quality Gates**: Only consider implementations where tests pass
git branch -d simple-cli-1 - **Easy Integration**: Merge the best solution
git branch -d simple-cli-2
git branch -d simple-cli-3
```
--- ---
@ -398,12 +539,17 @@ git branch -d simple-cli-3
| `/init` | Generate initial CLAUDE.md | | `/init` | Generate initial CLAUDE.md |
| `/permissions` | Manage tool permissions | | `/permissions` | Manage tool permissions |
| `/clear` | Clear context between tasks | | `/clear` | Clear context between tasks |
| `/agents` | Create and manage subagents |
| `/primer` | Analyze repository structure |
| `ESC` | Interrupt Claude | | `ESC` | Interrupt Claude |
| `Shift+Tab` | Enter planning mode | | `Shift+Tab` | Enter planning mode |
| `/generate-prp INITIAL.md` | Create implementation blueprint | | `/generate-prp INITIAL.md` | Create implementation blueprint |
| `/execute-prp PRPs/feature.md` | Implement from blueprint | | `/execute-prp PRPs/feature.md` | Implement from blueprint |
| `/prep-parallel [feature] [count]` | Setup parallel worktrees | | `/prep-parallel [feature] [count]` | Setup parallel worktrees |
| `/execute-parallel [feature] [plan] [count]` | Run parallel implementations | | `/execute-parallel [feature] [plan] [count]` | Run parallel implementations |
| `/fix-github-issue [number]` | Auto-fix GitHub issues |
| `/prep-parallel [feature] [count]` | Setup parallel worktrees |
| `/execute-parallel [feature] [plan] [count]` | Run parallel implementations |
--- ---
@ -412,16 +558,16 @@ git branch -d simple-cli-3
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) - [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
- [MCP Server Library](https://github.com/modelcontextprotocol) - [MCP Server Library](https://github.com/modelcontextprotocol)
- [Context Engineering Guide](contextengineering.md)
--- ---
## 🚀 Next Steps ## 🚀 Next Steps
1. Set up your CLAUDE.md file with project-specific context 1. **Start Simple**: Set up CLAUDE.md and basic permissions
2. Configure permissions for smooth workflow 2. **Add Slash Commands**: Create custom commands for your workflow
3. Try context engineering with a small feature 3. **Install MCP Servers**: Add Serena for enhanced coding capabilities
4. Experiment with parallel agent development 4. **Implement Subagents**: Add specialists for your tech stack
5. Integrate MCP servers for your tech stack 5. **Configure Hooks**: Automate repetitive tasks
6. **Try Parallel Development**: Experiment with multiple approaches
Remember: Claude Code is most powerful when you provide clear context, specific instructions, and iterative feedback. Happy coding! 🎉 Remember: Claude Code is most powerful when you provide clear context, specific examples, and comprehensive validation. Happy coding! 🎉

33
claude-code-full-guide/install_claude_code_windows.md Normal file
View File

@ -0,0 +1,33 @@
## Installing Claude Code on Windows (with WSL)
Claude Code only supports Linux and MacOS by default. To use Claude Code with Windows, you can use WSL.
1. Go to the Microsoft Store
2. Search for Ubuntu WSL and install
3. Open WSL in a terminal
4. Run the following commands (this follows best security practices):
```bash
# First, save a list of your existing global packages for later migration
npm list -g --depth=0 > ~/npm-global-packages.txt
# Create a directory for your global packages
mkdir -p ~/.npm-global
# Configure npm to use the new directory path
npm config set prefix ~/.npm-global
# Note: Replace ~/.bashrc with ~/.zshrc, ~/.profile, or other appropriate file for your shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# Apply the new PATH setting
source ~/.bashrc
# Now reinstall Claude Code in the new location
npm install -g @anthropic-ai/claude-code
```
5. Now within your IDEs you can open a terminal with Ctrl + J (also use this hotkey to toggle it off) and you can click on the down arrow next to the plus to open an Ubuntu (WSL) terminal where you can run the "claude" command to start Claude Code.