Initial commit
This commit is contained in:
Zhongwei Li
447
skills/claude-code/references/best-practices.md
Normal file
447
skills/claude-code/references/best-practices.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# Best Practices
|
||||
|
||||
Guidelines for project organization, security, performance, collaboration, and cost management.
|
||||
|
||||
## Project Organization
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Keep `.claude/` directory in version control:
|
||||
|
||||
```
|
||||
project/
|
||||
├── .claude/
|
||||
│ ├── settings.json # Project settings
|
||||
│ ├── commands/ # Custom slash commands
|
||||
│ │ ├── test-all.md
|
||||
│ │ └── deploy.md
|
||||
│ ├── skills/ # Project-specific skills
|
||||
│ │ └── api-testing/
|
||||
│ ├── hooks.json # Hooks configuration
|
||||
│ ├── mcp.json # MCP servers (no secrets!)
|
||||
│ └── .env.example # Environment template
|
||||
├── .gitignore # Ignore .claude/.env
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
Document custom extensions:
|
||||
|
||||
**README.md:**
|
||||
```markdown
|
||||
## Claude Code Setup
|
||||
|
||||
### Custom Commands
|
||||
- `/test-all`: Run full test suite
|
||||
- `/deploy`: Deploy to staging
|
||||
|
||||
### Skills
|
||||
- `api-testing`: REST API testing utilities
|
||||
|
||||
### MCP Servers
|
||||
- `postgres`: Database access
|
||||
- `github`: Repository integration
|
||||
|
||||
### Environment Variables
|
||||
Copy `.claude/.env.example` to `.claude/.env` and fill in:
|
||||
- GITHUB_TOKEN
|
||||
- DATABASE_URL
|
||||
```
|
||||
|
||||
### Team Sharing
|
||||
|
||||
**What to commit:**
|
||||
- `.claude/settings.json`
|
||||
- `.claude/commands/`
|
||||
- `.claude/skills/`
|
||||
- `.claude/hooks.json`
|
||||
- `.claude/mcp.json` (without secrets)
|
||||
- `.claude/.env.example`
|
||||
|
||||
**What NOT to commit:**
|
||||
- `.claude/.env` (contains secrets)
|
||||
- `.claude/memory/` (optional)
|
||||
- `.claude/cache/`
|
||||
- API keys or tokens
|
||||
|
||||
**.gitignore:**
|
||||
```
|
||||
.claude/.env
|
||||
.claude/memory/
|
||||
.claude/cache/
|
||||
.claude/logs/
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### API Key Management
|
||||
|
||||
**Never commit API keys:**
|
||||
```bash
|
||||
# Use environment variables
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||||
|
||||
# Or .env file (gitignored)
|
||||
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .claude/.env
|
||||
```
|
||||
|
||||
**Rotate keys regularly:**
|
||||
```bash
|
||||
# Generate new key
|
||||
# Update in all environments
|
||||
# Revoke old key
|
||||
```
|
||||
|
||||
**Use workspace keys:**
|
||||
```bash
|
||||
# For team projects, use workspace API keys
|
||||
# Easier to manage and rotate
|
||||
# Better access control
|
||||
```
|
||||
|
||||
### Sandboxing
|
||||
|
||||
Enable sandboxing in production:
|
||||
|
||||
```json
|
||||
{
|
||||
"sandboxing": {
|
||||
"enabled": true,
|
||||
"allowedPaths": ["/workspace"],
|
||||
"networkAccess": "restricted",
|
||||
"allowedDomains": ["api.company.com"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Hook Security
|
||||
|
||||
Review hook scripts before execution:
|
||||
|
||||
```bash
|
||||
# Check hooks.json
|
||||
cat .claude/hooks.json | jq .
|
||||
|
||||
# Review scripts
|
||||
cat .claude/scripts/hook.sh
|
||||
|
||||
# Validate inputs in hooks
|
||||
#!/bin/bash
|
||||
if [[ ! "$TOOL_ARGS" =~ ^[a-zA-Z0-9_-]+$ ]]; then
|
||||
echo "Invalid input"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Plugin Security
|
||||
|
||||
Audit plugins before installation:
|
||||
|
||||
```bash
|
||||
# Review plugin source
|
||||
gh repo view username/plugin
|
||||
|
||||
# Check plugin.json
|
||||
tar -xzf plugin.tar.gz
|
||||
cat plugin.json
|
||||
|
||||
# Install from trusted sources only
|
||||
claude plugin install gh:anthropics/official-plugin
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Model Selection
|
||||
|
||||
Choose appropriate model for task:
|
||||
|
||||
**Haiku** - Fast, cost-effective:
|
||||
```bash
|
||||
claude --model haiku "fix typo in README"
|
||||
claude --model haiku "format code"
|
||||
```
|
||||
|
||||
**Sonnet** - Balanced (default):
|
||||
```bash
|
||||
claude "implement user authentication"
|
||||
claude "review this PR"
|
||||
```
|
||||
|
||||
**Opus** - Complex tasks:
|
||||
```bash
|
||||
claude --model opus "architect microservices system"
|
||||
claude --model opus "optimize algorithm performance"
|
||||
```
|
||||
|
||||
### Prompt Caching
|
||||
|
||||
Cache repeated context:
|
||||
|
||||
```typescript
|
||||
// Cache large codebase
|
||||
const response = await client.messages.create({
|
||||
model: 'claude-sonnet-4-5-20250929',
|
||||
system: [
|
||||
{
|
||||
type: 'text',
|
||||
text: largeCodebase,
|
||||
cache_control: { type: 'ephemeral' }
|
||||
}
|
||||
],
|
||||
messages: [...]
|
||||
});
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- 90% cost reduction on cached tokens
|
||||
- Faster responses
|
||||
- Better for iterative development
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Implement rate limiting in hooks:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .claude/scripts/rate-limit.sh
|
||||
|
||||
REQUESTS_FILE=".claude/requests.log"
|
||||
MAX_REQUESTS=100
|
||||
WINDOW=3600 # 1 hour
|
||||
|
||||
# Count recent requests
|
||||
RECENT=$(find $REQUESTS_FILE -mmin -60 | wc -l)
|
||||
|
||||
if [ $RECENT -ge $MAX_REQUESTS ]; then
|
||||
echo "Rate limit exceeded"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo $(date) >> $REQUESTS_FILE
|
||||
```
|
||||
|
||||
### Token Management
|
||||
|
||||
Monitor token usage:
|
||||
|
||||
```bash
|
||||
# Check usage
|
||||
claude usage show
|
||||
|
||||
# Set limits
|
||||
claude config set maxTokens 8192
|
||||
|
||||
# Track costs
|
||||
claude analytics cost --group-by project
|
||||
```
|
||||
|
||||
## Team Collaboration
|
||||
|
||||
### Standardize Commands
|
||||
|
||||
Create consistent slash commands:
|
||||
|
||||
```markdown
|
||||
# .claude/commands/test.md
|
||||
Run test suite with coverage report.
|
||||
|
||||
Options:
|
||||
- {{suite}}: Specific test suite (optional)
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/test
|
||||
/test unit
|
||||
/test integration
|
||||
```
|
||||
|
||||
### Share Skills
|
||||
|
||||
Create team skills via plugins:
|
||||
|
||||
```bash
|
||||
# Create team plugin
|
||||
cd .claude/plugins/team-plugin
|
||||
cat > plugin.json <<EOF
|
||||
{
|
||||
"name": "team-plugin",
|
||||
"skills": ["skills/*/"],
|
||||
"commands": ["commands/*.md"]
|
||||
}
|
||||
EOF
|
||||
|
||||
# Package and share
|
||||
tar -czf team-plugin.tar.gz .
|
||||
```
|
||||
|
||||
### Consistent Settings
|
||||
|
||||
Use project settings for consistency:
|
||||
|
||||
**.claude/settings.json:**
|
||||
```json
|
||||
{
|
||||
"model": "claude-sonnet-4-5-20250929",
|
||||
"maxTokens": 8192,
|
||||
"outputStyle": "technical-writer",
|
||||
"thinking": {
|
||||
"enabled": true,
|
||||
"budget": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Settings
|
||||
|
||||
Use project memory for shared context:
|
||||
|
||||
```json
|
||||
{
|
||||
"memory": {
|
||||
"enabled": true,
|
||||
"location": "project"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Shared project knowledge
|
||||
- Consistent behavior across team
|
||||
- Reduced onboarding time
|
||||
|
||||
## Cost Management
|
||||
|
||||
### Budget Limits
|
||||
|
||||
Set budget limits in hooks:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .claude/scripts/budget-check.sh
|
||||
|
||||
MONTHLY_BUDGET=1000
|
||||
CURRENT_SPEND=$(claude analytics cost --format json | jq '.total')
|
||||
|
||||
if (( $(echo "$CURRENT_SPEND > $MONTHLY_BUDGET" | bc -l) )); then
|
||||
echo "⚠️ Monthly budget exceeded: \$$CURRENT_SPEND / \$$MONTHLY_BUDGET"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Usage Monitoring
|
||||
|
||||
Monitor via analytics API:
|
||||
|
||||
```bash
|
||||
# Daily usage report
|
||||
claude analytics usage --start $(date -d '1 day ago' +%Y-%m-%d)
|
||||
|
||||
# Cost by user
|
||||
claude analytics cost --group-by user
|
||||
|
||||
# Export to CSV
|
||||
claude analytics export --format csv > usage.csv
|
||||
```
|
||||
|
||||
### Cost Optimization
|
||||
|
||||
**Use Haiku for simple tasks:**
|
||||
```bash
|
||||
# Expensive (Sonnet)
|
||||
claude "fix typo in README"
|
||||
|
||||
# Cheap (Haiku)
|
||||
claude --model haiku "fix typo in README"
|
||||
```
|
||||
|
||||
**Enable caching:**
|
||||
```json
|
||||
{
|
||||
"caching": {
|
||||
"enabled": true,
|
||||
"ttl": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Batch operations:**
|
||||
```bash
|
||||
# Instead of multiple requests
|
||||
claude "fix file1.js"
|
||||
claude "fix file2.js"
|
||||
claude "fix file3.js"
|
||||
|
||||
# Batch them
|
||||
claude "fix all files: file1.js file2.js file3.js"
|
||||
```
|
||||
|
||||
**Track per-project costs:**
|
||||
```bash
|
||||
# Tag projects
|
||||
claude --project my-project "implement feature"
|
||||
|
||||
# View project costs
|
||||
claude analytics cost --project my-project
|
||||
```
|
||||
|
||||
## Development Workflows
|
||||
|
||||
### Feature Development
|
||||
|
||||
```bash
|
||||
# 1. Plan feature
|
||||
claude /plan "implement user authentication"
|
||||
|
||||
# 2. Create checkpoint
|
||||
claude checkpoint create "before auth implementation"
|
||||
|
||||
# 3. Implement
|
||||
claude /cook "implement user authentication"
|
||||
|
||||
# 4. Test
|
||||
claude /test
|
||||
|
||||
# 5. Review
|
||||
claude "review authentication implementation"
|
||||
|
||||
# 6. Commit
|
||||
claude /git:cm
|
||||
```
|
||||
|
||||
### Bug Fixing
|
||||
|
||||
```bash
|
||||
# 1. Debug
|
||||
claude /debug "login button not working"
|
||||
|
||||
# 2. Fix
|
||||
claude /fix:fast "fix login button issue"
|
||||
|
||||
# 3. Test
|
||||
claude /test
|
||||
|
||||
# 4. Commit
|
||||
claude /git:cm
|
||||
```
|
||||
|
||||
### Code Review
|
||||
|
||||
```bash
|
||||
# Review PR
|
||||
claude "review PR #123"
|
||||
|
||||
# Check security
|
||||
claude "review for security vulnerabilities"
|
||||
|
||||
# Verify tests
|
||||
claude "check test coverage"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- Security guide: https://docs.claude.com/claude-code/security
|
||||
- Cost tracking: https://docs.claude.com/claude-code/costs
|
||||
- Team setup: https://docs.claude.com/claude-code/overview
|
||||
- API usage: `references/api-reference.md`
|
||||
Reference in New Issue
Block a user