claudeguide-engineer 1.14.8

package/.claude/skills/claude-code/references/best-practices.md

@@ -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`