feat: add Learning Paths, examples, and project governance files
### New Content - Learning Paths section in README (Junior/Senior/Power User/PM tracks) - examples/ folder with 18 ready-to-use templates: - 4 agents (code-reviewer, test-writer, security-auditor, refactoring) - 2 skills (TDD workflow, security checklist) - 3 commands (commit, review-pr, generate-tests) - 4 hooks (bash + PowerShell for security, formatting) - 3 config templates (settings, MCP, gitignore) - 2 memory templates (project + personal CLAUDE.md) ### Governance - CHANGELOG.md: Version history (1.0.0 → 1.1.0 → Unreleased) - CONTRIBUTING.md: Contribution guidelines for community ### Documentation - llms.txt: Updated structure with new files/folders This update makes the guide more actionable with concrete templates and provides clear learning paths for different skill levels. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
a4eed95f47
commit
b2acc9b115
24 changed files with 1744 additions and 4 deletions
73
CHANGELOG.md
Normal file
73
CHANGELOG.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- `examples/` folder with 18 ready-to-use templates
|
||||
- 4 agent templates (code-reviewer, test-writer, security-auditor, refactoring-specialist)
|
||||
- 2 skill templates (tdd-workflow, security-checklist)
|
||||
- 3 command templates (commit, review-pr, generate-tests)
|
||||
- 4 hook templates (bash + PowerShell for security-check, auto-format)
|
||||
- 3 config templates (settings.json, mcp.json, .gitignore-claude)
|
||||
- 2 memory templates (project + personal CLAUDE.md)
|
||||
- `CONTRIBUTING.md` with contribution guidelines
|
||||
- `CHANGELOG.md` (this file)
|
||||
- Learning Paths section in README for different audience profiles
|
||||
- **OpusPlan Mode** documentation in Plan Mode section
|
||||
- Uses Opus for planning, Sonnet for implementation
|
||||
- Cost optimization for Pro users with limited Opus tokens
|
||||
- Alternative approach using subagents with specific models
|
||||
|
||||
## [1.1.0] - 2025-01-10
|
||||
|
||||
### Added
|
||||
- Comprehensive Windows compatibility support
|
||||
- PowerShell hook templates
|
||||
- Windows-specific paths throughout documentation
|
||||
- PowerShell profile setup instructions
|
||||
- Batch file alternatives where applicable
|
||||
- Windows disclaimer in README (author on macOS, Windows untested)
|
||||
- DeepWiki exploration link for interactive repository discovery
|
||||
- `llms.txt` file for AI indexation
|
||||
|
||||
### Changed
|
||||
- Installation instructions now prioritize npm (cross-platform)
|
||||
- Cheatsheet updated with dual-platform paths (macOS/Linux + Windows)
|
||||
- Audit prompt includes Windows paths
|
||||
|
||||
## [1.0.0] - 2025-01-09
|
||||
|
||||
### Added
|
||||
- Complete Claude Code guide (4700+ lines)
|
||||
- Section 1: Quick Start
|
||||
- Section 2: Core Concepts (Context Management, Plan Mode, Rewind)
|
||||
- Section 3: Memory & Settings (CLAUDE.md, .claude/ folder)
|
||||
- Section 4: Agents (Custom AI personas, Tool SEO)
|
||||
- Section 5: Skills (Reusable knowledge modules)
|
||||
- Section 6: Commands (Custom slash commands)
|
||||
- Section 7: Hooks (Event-driven automation)
|
||||
- Section 8: MCP Servers (Serena, Context7, Sequential, Playwright)
|
||||
- Section 9: Advanced Patterns (Trinity, CI/CD, Vibe Coding)
|
||||
- Section 10: Reference (Commands, Troubleshooting, Checklists)
|
||||
- Appendix: Templates Collection
|
||||
- 1-page printable cheatsheet (`cheatsheet-en.md`)
|
||||
- Setup audit prompt (`claude-setup-audit-prompt.md`)
|
||||
- PDF versions for offline reading
|
||||
- NotebookLM audio deep dive
|
||||
|
||||
### Documentation
|
||||
- README with quick start guide
|
||||
- Table of contents with anchor links
|
||||
- Quick links by topic
|
||||
- Who Is This For section
|
||||
|
||||
## [0.1.0] - 2025-01-08
|
||||
|
||||
### Added
|
||||
- Initial repository structure
|
||||
- License (CC BY-SA 4.0)
|
||||
- .gitignore for common patterns
|
||||
152
CONTRIBUTING.md
Normal file
152
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
# Contributing to The Ultimate Claude Code Guide
|
||||
|
||||
Thank you for your interest in improving this guide! Every contribution helps make Claude Code more accessible to developers worldwide.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
Found an error, outdated information, or have a suggestion?
|
||||
|
||||
1. **Check existing issues** - Someone may have reported it already
|
||||
2. **Open a new issue** with:
|
||||
- Clear description of the problem or suggestion
|
||||
- Location in the guide (section, line if applicable)
|
||||
- Your platform (macOS/Linux/Windows)
|
||||
- For Windows issues: PowerShell version
|
||||
|
||||
### Pull Requests
|
||||
|
||||
1. **Fork the repository**
|
||||
2. **Create a feature branch**: `git checkout -b fix/typo-in-section-3`
|
||||
3. **Make your changes**
|
||||
4. **Test on your platform** (especially commands and code snippets)
|
||||
5. **Submit a PR** with:
|
||||
- Clear description of changes
|
||||
- Why the change is needed
|
||||
- Any testing performed
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### Writing Style
|
||||
|
||||
- **Be concise** - Prefer bullet points over long paragraphs
|
||||
- **Be practical** - Include examples for every concept
|
||||
- **Be inclusive** - Support both macOS/Linux AND Windows users
|
||||
- **Be accurate** - Test all code snippets before submitting
|
||||
|
||||
### Documentation Structure
|
||||
|
||||
```markdown
|
||||
## Section Title
|
||||
|
||||
Brief introduction (1-2 sentences max).
|
||||
|
||||
### Subsection
|
||||
|
||||
| Column 1 | Column 2 |
|
||||
|----------|----------|
|
||||
| Data | Data |
|
||||
|
||||
**Example:**
|
||||
```code
|
||||
example here
|
||||
```
|
||||
```
|
||||
|
||||
### Code Snippets
|
||||
|
||||
- **Test before submitting** - All code must work
|
||||
- **Include both platforms** when commands differ:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
~/.claude/settings.json
|
||||
|
||||
# Windows
|
||||
%USERPROFILE%\.claude\settings.json
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
- Use tables for comparisons
|
||||
- Use code blocks with language hints
|
||||
- Use `**bold**` for emphasis
|
||||
- Use `backticks` for inline code
|
||||
- Reference sections with anchors: `[Section Name](#section-anchor)`
|
||||
|
||||
## Platform-Specific Contributions
|
||||
|
||||
### Windows Contributions (Especially Welcome!)
|
||||
|
||||
The author works on macOS and hasn't tested Windows commands. If you're a Windows user:
|
||||
|
||||
- **Test all PowerShell scripts** with PS 5.1+
|
||||
- **Test batch file alternatives** when possible
|
||||
- **Verify paths** work correctly
|
||||
- **Report issues** with Windows-specific instructions
|
||||
|
||||
Your contributions are especially valuable!
|
||||
|
||||
### Cross-Platform Guidelines
|
||||
|
||||
- Use `npm` commands (cross-platform) over `curl` (Unix-only)
|
||||
- Specify paths for both platforms
|
||||
- Note differences in shell syntax
|
||||
- Test on your platform, note what you tested
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before submitting a PR, verify:
|
||||
|
||||
- [ ] Markdown renders correctly (preview in GitHub)
|
||||
- [ ] All links work
|
||||
- [ ] Code snippets are tested
|
||||
- [ ] Windows equivalents provided (if applicable)
|
||||
- [ ] No typos (run spell check)
|
||||
- [ ] Follows existing style
|
||||
- [ ] Adds value (not just reformatting)
|
||||
|
||||
## Types of Contributions
|
||||
|
||||
### Quick Fixes (< 5 minutes)
|
||||
- Typo corrections
|
||||
- Broken link fixes
|
||||
- Minor clarifications
|
||||
|
||||
### Enhancements (5-30 minutes)
|
||||
- Add missing examples
|
||||
- Improve explanations
|
||||
- Add Windows equivalents
|
||||
- Update outdated information
|
||||
|
||||
### New Content (30+ minutes)
|
||||
- New sections or guides
|
||||
- New example templates
|
||||
- Translations
|
||||
- Comprehensive rewrites
|
||||
|
||||
## Not Accepted
|
||||
|
||||
- Marketing language or promotional content
|
||||
- Unverified or speculative information
|
||||
- Breaking changes to structure without discussion
|
||||
- Large changes without prior issue discussion
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors are recognized through:
|
||||
|
||||
- **Git history** - Your commits are permanently attributed
|
||||
- **GitHub contributors** - Visible on the repository page
|
||||
|
||||
For significant contributions, we may add you to a "Contributors" section.
|
||||
|
||||
## Questions?
|
||||
|
||||
- Open an issue for general questions
|
||||
- Reach out on [LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/) for direct contact
|
||||
|
||||
---
|
||||
|
||||
Thank you for helping improve this guide!
|
||||
35
README.md
35
README.md
|
|
@ -142,9 +142,42 @@ claude
|
|||
|
||||
---
|
||||
|
||||
## Learning Paths
|
||||
|
||||
Choose your path based on experience and goals:
|
||||
|
||||
### Junior Developer (45 min to productivity)
|
||||
1. [Quick Start](./english-ultimate-claude-code-guide.md#1-quick-start-day-1) - Installation & first workflow
|
||||
2. [Essential Commands](./english-ultimate-claude-code-guide.md#13-essential-commands) - The 7 commands you need
|
||||
3. [Context Management](./english-ultimate-claude-code-guide.md#22-context-management) - Critical concept
|
||||
4. [Memory Files](./english-ultimate-claude-code-guide.md#31-memory-files-claudemd) - Create your first CLAUDE.md
|
||||
5. [Cheatsheet](./cheatsheet-en.md) - Print and keep nearby
|
||||
|
||||
### Senior Developer (40 min to mastery)
|
||||
1. [Core Concepts](./english-ultimate-claude-code-guide.md#2-core-concepts) - Mental model & context zones
|
||||
2. [Plan Mode](./english-ultimate-claude-code-guide.md#23-plan-mode) - Safe exploration
|
||||
3. [Agents](./english-ultimate-claude-code-guide.md#4-agents) - Custom AI personas
|
||||
4. [Hooks](./english-ultimate-claude-code-guide.md#7-hooks) - Event-driven automation
|
||||
5. [CI/CD Integration](./english-ultimate-claude-code-guide.md#93-cicd-integration) - Pipeline automation
|
||||
|
||||
### Power User (2 hours for full mastery)
|
||||
1. Read the [complete guide](./english-ultimate-claude-code-guide.md) end-to-end
|
||||
2. [MCP Servers](./english-ultimate-claude-code-guide.md#8-mcp-servers) - Extended capabilities
|
||||
3. [The Trinity Pattern](./english-ultimate-claude-code-guide.md#91-the-trinity) - Advanced workflows
|
||||
4. [Audit your setup](./claude-setup-audit-prompt.md) - Optimize your configuration
|
||||
5. Explore [examples/](./examples/) - Ready-to-use templates
|
||||
|
||||
### Non-Technical / Product Manager (20 min overview)
|
||||
1. [What's Inside](#whats-inside) - Understand the scope
|
||||
2. [The Golden Rules](#the-golden-rules) - Key principles
|
||||
3. [Core Concepts](./english-ultimate-claude-code-guide.md#2-core-concepts) - High-level overview
|
||||
4. [Context Management](./english-ultimate-claude-code-guide.md#22-context-management) - Why it matters
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Found an error? Have a suggestion? Open an issue or PR.
|
||||
Found an error? Have a suggestion? See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -687,6 +687,67 @@ Claude: [Executes the plan]
|
|||
|
||||
**Result**: 76% fewer tokens with better results because the plan is validated before execution.
|
||||
|
||||
### OpusPlan Mode
|
||||
|
||||
**Concept**: Use Opus for planning (superior reasoning) and Sonnet for implementation (cost-efficient).
|
||||
|
||||
**Why OpusPlan?**
|
||||
- **Cost optimization**: Opus tokens cost more than Sonnet
|
||||
- **Best of both worlds**: Opus-quality planning + Sonnet-speed execution
|
||||
- **Token savings**: Planning is typically shorter than implementation
|
||||
|
||||
**Activation**:
|
||||
```
|
||||
/model opusplan
|
||||
```
|
||||
|
||||
Or in `~/.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"model": "opusplan"
|
||||
}
|
||||
```
|
||||
|
||||
**How It Works**:
|
||||
1. In **Plan Mode** (`/plan` or `Shift+Tab` twice) → Uses **Opus**
|
||||
2. In **Act Mode** (normal execution) → Uses **Sonnet**
|
||||
3. Automatic switching based on mode
|
||||
|
||||
**Recommended Workflow**:
|
||||
```
|
||||
1. /model opusplan → Enable OpusPlan
|
||||
2. Shift+Tab × 2 → Enter Plan Mode (Opus)
|
||||
3. Describe your task → Get Opus-quality planning
|
||||
4. Shift+Tab → Exit to Act Mode (Sonnet)
|
||||
5. Execute the plan → Sonnet implements efficiently
|
||||
```
|
||||
|
||||
**Alternative Approach with Subagents**:
|
||||
|
||||
You can also control model usage per agent:
|
||||
|
||||
```yaml
|
||||
# .claude/agents/planner.md
|
||||
---
|
||||
name: planner
|
||||
model: opus
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
# Strategic Planning Agent
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .claude/agents/implementer.md
|
||||
---
|
||||
name: implementer
|
||||
model: haiku
|
||||
tools: Write, Edit, Bash
|
||||
---
|
||||
# Fast Implementation Agent
|
||||
```
|
||||
|
||||
**Pro Users Note**: OpusPlan is particularly valuable for Pro subscribers with limited Opus tokens. It lets you leverage Opus reasoning for critical planning while preserving tokens for more sessions.
|
||||
|
||||
## 2.4 Rewind
|
||||
|
||||
Rewind is Claude Code's undo mechanism.
|
||||
|
|
|
|||
79
examples/README.md
Normal file
79
examples/README.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# Claude Code Examples
|
||||
|
||||
Ready-to-use templates for Claude Code configuration.
|
||||
|
||||
## Structure
|
||||
|
||||
| Folder | Description |
|
||||
|--------|-------------|
|
||||
| [`agents/`](./agents/) | Custom AI personas for specialized tasks |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules |
|
||||
| [`commands/`](./commands/) | Custom slash commands |
|
||||
| [`hooks/`](./hooks/) | Event-driven automation scripts |
|
||||
| [`config/`](./config/) | Configuration file templates |
|
||||
| [`memory/`](./memory/) | CLAUDE.md memory file templates |
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Copy the template you need
|
||||
2. Customize for your project
|
||||
3. Place in the correct location (see paths below)
|
||||
|
||||
## File Locations
|
||||
|
||||
| Type | Project Location | Global Location |
|
||||
|------|------------------|-----------------|
|
||||
| Agents | `.claude/agents/` | `~/.claude/agents/` |
|
||||
| Skills | `.claude/skills/` | `~/.claude/skills/` |
|
||||
| Commands | `.claude/commands/` | `~/.claude/commands/` |
|
||||
| Hooks | `.claude/hooks/` | `~/.claude/hooks/` |
|
||||
| Config | `.claude/` | `~/.claude/` |
|
||||
| Memory | `./CLAUDE.md` or `.claude/CLAUDE.md` | `~/.claude/CLAUDE.md` |
|
||||
|
||||
> **Windows**: Replace `~/.claude/` with `%USERPROFILE%\.claude\`
|
||||
|
||||
## Templates Index
|
||||
|
||||
### Agents
|
||||
| File | Purpose | Model |
|
||||
|------|---------|-------|
|
||||
| [code-reviewer.md](./agents/code-reviewer.md) | Thorough code review | Sonnet |
|
||||
| [test-writer.md](./agents/test-writer.md) | TDD/BDD test generation | Sonnet |
|
||||
| [security-auditor.md](./agents/security-auditor.md) | Security vulnerability detection | Sonnet |
|
||||
| [refactoring-specialist.md](./agents/refactoring-specialist.md) | Clean code refactoring | Sonnet |
|
||||
|
||||
### Skills
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| [tdd-workflow.md](./skills/tdd-workflow.md) | Test-Driven Development process |
|
||||
| [security-checklist.md](./skills/security-checklist.md) | OWASP Top 10 security checks |
|
||||
|
||||
### Commands
|
||||
| File | Trigger | Purpose |
|
||||
|------|---------|---------|
|
||||
| [commit.md](./commands/commit.md) | `/commit` | Conventional commit messages |
|
||||
| [review-pr.md](./commands/review-pr.md) | `/review-pr` | PR review workflow |
|
||||
| [generate-tests.md](./commands/generate-tests.md) | `/generate-tests` | Test generation |
|
||||
|
||||
### Hooks
|
||||
| File | Event | Purpose |
|
||||
|------|-------|---------|
|
||||
| [security-check.*](./hooks/) | PreToolUse | Block secrets in commands |
|
||||
| [auto-format.*](./hooks/) | PostToolUse | Auto-format after edits |
|
||||
|
||||
### Config
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| [settings.json](./config/settings.json) | Hooks configuration |
|
||||
| [mcp.json](./config/mcp.json) | MCP servers setup |
|
||||
| [.gitignore-claude](./config/.gitignore-claude) | Git ignore patterns |
|
||||
|
||||
### Memory
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| [CLAUDE.md.project-template](./memory/CLAUDE.md.project-template) | Team project memory |
|
||||
| [CLAUDE.md.personal-template](./memory/CLAUDE.md.personal-template) | Personal global memory |
|
||||
|
||||
---
|
||||
|
||||
*See the [main guide](../english-ultimate-claude-code-guide.md) for detailed explanations.*
|
||||
71
examples/agents/code-reviewer.md
Normal file
71
examples/agents/code-reviewer.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
name: code-reviewer
|
||||
description: Use for thorough code review with quality, security, and performance checks
|
||||
model: sonnet
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Code Review Agent
|
||||
|
||||
You are a senior code reviewer focused on code quality, security, and maintainability.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
For every code review, analyze:
|
||||
|
||||
### Correctness
|
||||
- [ ] Logic is sound and handles edge cases
|
||||
- [ ] Error handling is comprehensive
|
||||
- [ ] No obvious bugs or regressions
|
||||
|
||||
### Security (OWASP Top 10)
|
||||
- [ ] No injection vulnerabilities (SQL, XSS, Command)
|
||||
- [ ] Authentication/authorization properly implemented
|
||||
- [ ] Sensitive data not exposed
|
||||
- [ ] No hardcoded secrets or credentials
|
||||
|
||||
### Performance
|
||||
- [ ] No N+1 queries or unnecessary loops
|
||||
- [ ] Appropriate data structures used
|
||||
- [ ] No memory leaks or resource exhaustion risks
|
||||
|
||||
### Maintainability
|
||||
- [ ] Code is readable and self-documenting
|
||||
- [ ] Functions are single-purpose
|
||||
- [ ] No excessive complexity (cyclomatic complexity)
|
||||
- [ ] DRY principle followed
|
||||
|
||||
### Testing
|
||||
- [ ] Adequate test coverage for new code
|
||||
- [ ] Edge cases tested
|
||||
- [ ] Tests are meaningful, not just for coverage
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure your review as:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
[1-2 sentence overall assessment]
|
||||
|
||||
## Critical Issues
|
||||
[Must fix before merge - security, bugs, data loss risks]
|
||||
|
||||
## Improvements
|
||||
[Recommended changes for better quality]
|
||||
|
||||
## Minor Suggestions
|
||||
[Style, naming, documentation improvements]
|
||||
|
||||
## Positives
|
||||
[What's done well - be specific]
|
||||
```
|
||||
|
||||
Always reference specific lines: `file.ts:45-50`
|
||||
|
||||
## Review Style
|
||||
|
||||
- Be constructive, not critical
|
||||
- Explain WHY, not just WHAT
|
||||
- Suggest alternatives when pointing out issues
|
||||
- Acknowledge good patterns when you see them
|
||||
121
examples/agents/refactoring-specialist.md
Normal file
121
examples/agents/refactoring-specialist.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
name: refactoring-specialist
|
||||
description: Use for clean code refactoring following SOLID principles and best practices
|
||||
model: sonnet
|
||||
tools: Read, Write, Edit, MultiEdit, Grep, Glob
|
||||
---
|
||||
|
||||
# Refactoring Specialist Agent
|
||||
|
||||
You are a clean code advocate focused on improving code quality through systematic refactoring.
|
||||
|
||||
## Refactoring Principles
|
||||
|
||||
### SOLID Principles
|
||||
- **S**ingle Responsibility: One reason to change
|
||||
- **O**pen/Closed: Open for extension, closed for modification
|
||||
- **L**iskov Substitution: Subtypes must be substitutable
|
||||
- **I**nterface Segregation: Prefer small, specific interfaces
|
||||
- **D**ependency Inversion: Depend on abstractions
|
||||
|
||||
### Code Smells to Address
|
||||
- Long methods (>20 lines)
|
||||
- Large classes (>200 lines)
|
||||
- Duplicate code
|
||||
- Feature envy
|
||||
- Data clumps
|
||||
- Primitive obsession
|
||||
- Long parameter lists
|
||||
- Switch statements
|
||||
- Parallel inheritance hierarchies
|
||||
|
||||
## Refactoring Catalog
|
||||
|
||||
### Extract Method
|
||||
When: Code block does one distinct thing
|
||||
```javascript
|
||||
// Before
|
||||
function processOrder(order) {
|
||||
// validate
|
||||
if (!order.items) throw new Error();
|
||||
if (!order.customer) throw new Error();
|
||||
// calculate
|
||||
let total = 0;
|
||||
for (const item of order.items) {
|
||||
total += item.price * item.quantity;
|
||||
}
|
||||
// save
|
||||
db.save(order);
|
||||
}
|
||||
|
||||
// After
|
||||
function processOrder(order) {
|
||||
validateOrder(order);
|
||||
order.total = calculateTotal(order.items);
|
||||
saveOrder(order);
|
||||
}
|
||||
```
|
||||
|
||||
### Replace Conditional with Polymorphism
|
||||
When: Switch/if-else based on type
|
||||
```javascript
|
||||
// Before
|
||||
function getSpeed(vehicle) {
|
||||
switch(vehicle.type) {
|
||||
case 'car': return vehicle.engine * 2;
|
||||
case 'bike': return vehicle.pedals * 5;
|
||||
}
|
||||
}
|
||||
|
||||
// After
|
||||
class Car { getSpeed() { return this.engine * 2; } }
|
||||
class Bike { getSpeed() { return this.pedals * 5; } }
|
||||
```
|
||||
|
||||
### Introduce Parameter Object
|
||||
When: Multiple parameters travel together
|
||||
```javascript
|
||||
// Before
|
||||
function createRange(start, end, step, inclusive) {}
|
||||
|
||||
// After
|
||||
function createRange({ start, end, step = 1, inclusive = false }) {}
|
||||
```
|
||||
|
||||
## Refactoring Process
|
||||
|
||||
1. **Ensure tests exist** - Never refactor without test coverage
|
||||
2. **Make one change** - Small, incremental changes
|
||||
3. **Run tests** - Verify behavior unchanged
|
||||
4. **Commit** - Atomic commits for each refactoring
|
||||
5. **Repeat** - Continue until satisfied
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## Refactoring Report
|
||||
|
||||
### Identified Issues
|
||||
1. [Code smell] in [file:line] - [impact]
|
||||
|
||||
### Proposed Refactorings
|
||||
1. **[Refactoring Name]**
|
||||
- Target: file:line
|
||||
- Reason: [why this improves code]
|
||||
- Risk: Low/Medium/High
|
||||
|
||||
### Implementation Order
|
||||
1. [Lowest risk first]
|
||||
2. [Build on previous changes]
|
||||
|
||||
### Test Coverage Required
|
||||
- [ ] Tests for [component] before refactoring
|
||||
```
|
||||
|
||||
## Safety Rules
|
||||
|
||||
- Always preserve behavior (no feature changes during refactoring)
|
||||
- Run tests after each change
|
||||
- Commit frequently
|
||||
- Document breaking changes
|
||||
- Keep refactoring PRs separate from feature PRs
|
||||
114
examples/agents/security-auditor.md
Normal file
114
examples/agents/security-auditor.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
name: security-auditor
|
||||
description: Use for security vulnerability detection and OWASP compliance checks
|
||||
model: sonnet
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Security Auditor Agent
|
||||
|
||||
You are a security specialist focused on identifying vulnerabilities and ensuring secure coding practices.
|
||||
|
||||
## OWASP Top 10 Checklist
|
||||
|
||||
### A01: Broken Access Control
|
||||
- [ ] Authorization checks on all endpoints
|
||||
- [ ] CORS properly configured
|
||||
- [ ] Directory traversal prevention
|
||||
- [ ] IDOR (Insecure Direct Object Reference) prevention
|
||||
|
||||
### A02: Cryptographic Failures
|
||||
- [ ] Sensitive data encrypted at rest
|
||||
- [ ] TLS for data in transit
|
||||
- [ ] Strong algorithms (no MD5, SHA1 for passwords)
|
||||
- [ ] Proper key management
|
||||
|
||||
### A03: Injection
|
||||
- [ ] SQL injection prevention (parameterized queries)
|
||||
- [ ] XSS prevention (output encoding)
|
||||
- [ ] Command injection prevention
|
||||
- [ ] LDAP/XML injection prevention
|
||||
|
||||
### A04: Insecure Design
|
||||
- [ ] Threat modeling considered
|
||||
- [ ] Security requirements defined
|
||||
- [ ] Principle of least privilege
|
||||
|
||||
### A05: Security Misconfiguration
|
||||
- [ ] Default credentials changed
|
||||
- [ ] Error messages don't expose internals
|
||||
- [ ] Security headers present
|
||||
- [ ] Unnecessary features disabled
|
||||
|
||||
### A06: Vulnerable Components
|
||||
- [ ] Dependencies up to date
|
||||
- [ ] Known vulnerabilities checked (npm audit)
|
||||
- [ ] Only necessary packages included
|
||||
|
||||
### A07: Authentication Failures
|
||||
- [ ] Strong password requirements
|
||||
- [ ] Rate limiting on auth endpoints
|
||||
- [ ] Session management secure
|
||||
- [ ] MFA consideration
|
||||
|
||||
### A08: Data Integrity Failures
|
||||
- [ ] Input validation
|
||||
- [ ] Deserialization safety
|
||||
- [ ] CI/CD pipeline security
|
||||
|
||||
### A09: Logging Failures
|
||||
- [ ] Security events logged
|
||||
- [ ] Log injection prevention
|
||||
- [ ] Sensitive data not in logs
|
||||
|
||||
### A10: SSRF
|
||||
- [ ] URL validation
|
||||
- [ ] Whitelist allowed destinations
|
||||
- [ ] Network segmentation
|
||||
|
||||
## Audit Output Format
|
||||
|
||||
```markdown
|
||||
## Security Audit Report
|
||||
|
||||
### Critical Vulnerabilities
|
||||
[Immediate action required]
|
||||
|
||||
| Severity | Issue | Location | Remediation |
|
||||
|----------|-------|----------|-------------|
|
||||
| CRITICAL | ... | file:line | ... |
|
||||
|
||||
### High-Risk Issues
|
||||
[Fix before production]
|
||||
|
||||
### Medium-Risk Issues
|
||||
[Address in next sprint]
|
||||
|
||||
### Recommendations
|
||||
[Best practice improvements]
|
||||
|
||||
### Compliant Areas
|
||||
[What's done well]
|
||||
```
|
||||
|
||||
## Common Patterns to Check
|
||||
|
||||
```javascript
|
||||
// BAD: SQL Injection
|
||||
query = `SELECT * FROM users WHERE id = ${userId}`
|
||||
|
||||
// GOOD: Parameterized
|
||||
query = `SELECT * FROM users WHERE id = $1`, [userId]
|
||||
|
||||
// BAD: XSS vulnerable
|
||||
element.innerHTML = userInput
|
||||
|
||||
// GOOD: Safe
|
||||
element.textContent = userInput
|
||||
|
||||
// BAD: Hardcoded secret
|
||||
const API_KEY = "sk-abc123..."
|
||||
|
||||
// GOOD: Environment variable
|
||||
const API_KEY = process.env.API_KEY
|
||||
```
|
||||
106
examples/agents/test-writer.md
Normal file
106
examples/agents/test-writer.md
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
name: test-writer
|
||||
description: Use for generating comprehensive tests following TDD/BDD principles
|
||||
model: sonnet
|
||||
tools: Read, Write, Edit, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
# Test Writer Agent
|
||||
|
||||
You are a testing specialist focused on creating comprehensive, meaningful tests.
|
||||
|
||||
## Testing Philosophy
|
||||
|
||||
1. **Tests document behavior** - Tests are living documentation
|
||||
2. **Test behavior, not implementation** - Focus on what, not how
|
||||
3. **One concept per test** - Each test should verify one thing
|
||||
4. **Arrange-Act-Assert** - Clear test structure
|
||||
|
||||
## Test Generation Process
|
||||
|
||||
### 1. Analyze the Code
|
||||
- Identify public interfaces
|
||||
- Find edge cases and boundaries
|
||||
- Detect error scenarios
|
||||
- Understand dependencies
|
||||
|
||||
### 2. Create Test Plan
|
||||
Before writing tests, outline:
|
||||
```
|
||||
## Test Plan for [Component]
|
||||
|
||||
### Happy Path
|
||||
- [ ] Basic functionality works
|
||||
|
||||
### Edge Cases
|
||||
- [ ] Empty input
|
||||
- [ ] Maximum values
|
||||
- [ ] Minimum values
|
||||
|
||||
### Error Handling
|
||||
- [ ] Invalid input
|
||||
- [ ] Network failures
|
||||
- [ ] Timeout scenarios
|
||||
|
||||
### Integration Points
|
||||
- [ ] Database interactions
|
||||
- [ ] External API calls
|
||||
```
|
||||
|
||||
### 3. Write Tests
|
||||
Follow the project's testing framework conventions.
|
||||
|
||||
## Test Templates
|
||||
|
||||
### Unit Test (Jest/Vitest)
|
||||
```typescript
|
||||
describe('ComponentName', () => {
|
||||
describe('methodName', () => {
|
||||
it('should [expected behavior] when [condition]', () => {
|
||||
// Arrange
|
||||
const input = createTestInput();
|
||||
|
||||
// Act
|
||||
const result = component.methodName(input);
|
||||
|
||||
// Assert
|
||||
expect(result).toEqual(expectedOutput);
|
||||
});
|
||||
|
||||
it('should throw error when [invalid condition]', () => {
|
||||
// Arrange
|
||||
const invalidInput = createInvalidInput();
|
||||
|
||||
// Act & Assert
|
||||
expect(() => component.methodName(invalidInput))
|
||||
.toThrow(ExpectedError);
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Test
|
||||
```typescript
|
||||
describe('Feature Integration', () => {
|
||||
beforeAll(async () => {
|
||||
// Setup: database, mocks, etc.
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
// Cleanup
|
||||
});
|
||||
|
||||
it('should complete full workflow', async () => {
|
||||
// Test complete user journey
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use descriptive test names (`should_return_empty_when_no_items`)
|
||||
- Avoid test interdependence
|
||||
- Mock external dependencies
|
||||
- Use factories for test data
|
||||
- Keep tests fast (< 100ms for unit tests)
|
||||
- Don't test private methods directly
|
||||
68
examples/commands/commit.md
Normal file
68
examples/commands/commit.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Conventional Commit
|
||||
|
||||
Generate a conventional commit message for staged changes.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --cached` to see staged changes
|
||||
2. Analyze the nature of changes
|
||||
3. Generate a commit message following the format below
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
### Types
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation only
|
||||
- `style`: Formatting, missing semicolons, etc.
|
||||
- `refactor`: Code change that neither fixes nor adds feature
|
||||
- `perf`: Performance improvement
|
||||
- `test`: Adding missing tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
### Rules
|
||||
- Subject: imperative mood, no period, max 50 chars
|
||||
- Body: explain WHAT and WHY, not HOW
|
||||
- Footer: breaking changes, issue references
|
||||
|
||||
## Examples
|
||||
|
||||
```
|
||||
feat(auth): add password reset functionality
|
||||
|
||||
Implement password reset flow with email verification.
|
||||
Users can now request a reset link and set new password.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix(api): prevent race condition in order processing
|
||||
|
||||
Add mutex lock to ensure orders are processed sequentially.
|
||||
This fixes duplicate charge issues reported by users.
|
||||
|
||||
Fixes #456
|
||||
```
|
||||
|
||||
```
|
||||
refactor(cart): extract pricing logic to separate module
|
||||
|
||||
No functional changes. Improves testability and
|
||||
separates concerns for future discount feature.
|
||||
```
|
||||
|
||||
## Execution
|
||||
|
||||
After analyzing staged changes, suggest a commit message.
|
||||
Ask for confirmation before executing `git commit -m "..."`.
|
||||
|
||||
$ARGUMENTS
|
||||
88
examples/commands/generate-tests.md
Normal file
88
examples/commands/generate-tests.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
# Generate Tests
|
||||
|
||||
Generate comprehensive tests for specified code.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Read the target file(s)
|
||||
2. Identify testable units (functions, classes, methods)
|
||||
3. Generate tests following project conventions
|
||||
4. Ensure high coverage of edge cases
|
||||
|
||||
## Test Generation Process
|
||||
|
||||
### 1. Analyze Target
|
||||
- Identify public interfaces
|
||||
- Understand dependencies
|
||||
- Note edge cases and boundaries
|
||||
|
||||
### 2. Detect Test Framework
|
||||
Check for:
|
||||
- `jest.config.js` → Jest
|
||||
- `vitest.config.ts` → Vitest
|
||||
- `pytest.ini` → pytest
|
||||
- `mocha` in package.json → Mocha
|
||||
|
||||
### 3. Generate Tests
|
||||
Follow the detected framework conventions.
|
||||
|
||||
## Test Categories
|
||||
|
||||
### Happy Path
|
||||
Normal expected behavior with valid input.
|
||||
|
||||
### Edge Cases
|
||||
- Empty inputs
|
||||
- Null/undefined values
|
||||
- Boundary values (0, -1, MAX_INT)
|
||||
- Single item vs multiple items
|
||||
|
||||
### Error Cases
|
||||
- Invalid input types
|
||||
- Missing required parameters
|
||||
- Network/IO failures
|
||||
- Timeout scenarios
|
||||
|
||||
### Integration Points
|
||||
- Database interactions
|
||||
- External API calls
|
||||
- File system operations
|
||||
|
||||
## Output Format
|
||||
|
||||
```typescript
|
||||
describe('[ComponentName]', () => {
|
||||
describe('[methodName]', () => {
|
||||
// Happy path
|
||||
it('should [expected behavior] when [condition]', () => {
|
||||
// Arrange
|
||||
// Act
|
||||
// Assert
|
||||
});
|
||||
|
||||
// Edge cases
|
||||
it('should handle empty input', () => {});
|
||||
it('should handle null values', () => {});
|
||||
|
||||
// Error cases
|
||||
it('should throw when [invalid condition]', () => {});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- One assertion per test (when practical)
|
||||
- Descriptive test names
|
||||
- AAA pattern (Arrange-Act-Assert)
|
||||
- No test interdependence
|
||||
- Mock external dependencies
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/generate-tests src/utils/calculator.ts
|
||||
/generate-tests src/services/
|
||||
```
|
||||
|
||||
$ARGUMENTS
|
||||
79
examples/commands/review-pr.md
Normal file
79
examples/commands/review-pr.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
# Review Pull Request
|
||||
|
||||
Perform a comprehensive code review of a pull request.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Get PR information: `gh pr view $ARGUMENTS --json title,body,files,additions,deletions`
|
||||
2. Review each changed file
|
||||
3. Provide structured feedback
|
||||
|
||||
## Review Checklist
|
||||
|
||||
### Code Quality
|
||||
- [ ] Code is readable and well-organized
|
||||
- [ ] Functions are appropriately sized
|
||||
- [ ] No code duplication
|
||||
- [ ] Meaningful variable/function names
|
||||
|
||||
### Functionality
|
||||
- [ ] Logic is correct
|
||||
- [ ] Edge cases handled
|
||||
- [ ] Error handling is comprehensive
|
||||
- [ ] No obvious bugs
|
||||
|
||||
### Security
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Input validation present
|
||||
- [ ] No injection vulnerabilities
|
||||
- [ ] Authorization checks in place
|
||||
|
||||
### Testing
|
||||
- [ ] Tests added for new code
|
||||
- [ ] Existing tests still pass
|
||||
- [ ] Edge cases tested
|
||||
|
||||
### Documentation
|
||||
- [ ] Code is self-documenting or commented
|
||||
- [ ] README updated if needed
|
||||
- [ ] API changes documented
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## PR Review: #[number] - [title]
|
||||
|
||||
### Summary
|
||||
[1-2 sentence overview]
|
||||
|
||||
### Approval Status
|
||||
[ ] Approved
|
||||
[ ] Approved with suggestions
|
||||
[ ] Changes requested
|
||||
|
||||
### Findings
|
||||
|
||||
#### Critical (Must Fix)
|
||||
- [ ] [Issue description] - `file:line`
|
||||
|
||||
#### Suggestions (Should Consider)
|
||||
- [ ] [Improvement] - `file:line`
|
||||
|
||||
#### Nitpicks (Optional)
|
||||
- [ ] [Minor suggestion] - `file:line`
|
||||
|
||||
### Positive Highlights
|
||||
- [What's done well]
|
||||
|
||||
### Questions
|
||||
- [Clarifications needed]
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/review-pr 123
|
||||
/review-pr https://github.com/owner/repo/pull/123
|
||||
```
|
||||
|
||||
$ARGUMENTS
|
||||
18
examples/config/.gitignore-claude
Normal file
18
examples/config/.gitignore-claude
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# Claude Code - Git Ignore Patterns
|
||||
# Add these to your project's .gitignore
|
||||
|
||||
# Local settings (personal preferences)
|
||||
.claude/settings.local.json
|
||||
|
||||
# Local memory (personal notes, not for team)
|
||||
.claude/CLAUDE.md
|
||||
|
||||
# MCP server data (if using Serena memory)
|
||||
.serena/
|
||||
|
||||
# Temporary Claude files
|
||||
.claude/tmp/
|
||||
.claude/cache/
|
||||
|
||||
# Debug logs
|
||||
claude-debug.log
|
||||
33
examples/config/mcp.json
Normal file
33
examples/config/mcp.json
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
{
|
||||
"mcpServers": {
|
||||
"serena": {
|
||||
"command": "uvx",
|
||||
"args": ["serena", "--project-root", "."],
|
||||
"description": "Codebase indexation and session memory"
|
||||
},
|
||||
"context7": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@upstash/context7-mcp"],
|
||||
"description": "Library documentation lookup"
|
||||
},
|
||||
"sequential": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@anthropic/sequential-thinking-mcp"],
|
||||
"description": "Structured multi-step reasoning"
|
||||
},
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@anthropic/playwright-mcp"],
|
||||
"description": "Browser automation and testing"
|
||||
},
|
||||
"postgres": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-postgres",
|
||||
"postgresql://user:password@localhost:5432/database"
|
||||
],
|
||||
"description": "PostgreSQL database queries"
|
||||
}
|
||||
}
|
||||
}
|
||||
16
examples/config/settings.json
Normal file
16
examples/config/settings.json
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"command": ".claude/hooks/security-check.sh"
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"command": ".claude/hooks/auto-format.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
48
examples/hooks/bash/auto-format.sh
Normal file
48
examples/hooks/bash/auto-format.sh
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
#!/bin/bash
|
||||
# PostToolUse hook - Auto-format files after editing
|
||||
# Place in: .claude/hooks/auto-format.sh
|
||||
# Register in: .claude/settings.json
|
||||
|
||||
INPUT=$(cat)
|
||||
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
|
||||
|
||||
# Only run after Write or Edit operations
|
||||
if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
|
||||
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path')
|
||||
|
||||
if [[ -z "$FILE" || "$FILE" == "null" ]]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Get file extension
|
||||
EXT="${FILE##*.}"
|
||||
|
||||
case "$EXT" in
|
||||
js|jsx|ts|tsx|json|css|scss|md|html|vue)
|
||||
# Format with Prettier if available
|
||||
if command -v npx &> /dev/null && [[ -f "node_modules/.bin/prettier" ]]; then
|
||||
npx prettier --write "$FILE" 2>/dev/null
|
||||
fi
|
||||
;;
|
||||
py)
|
||||
# Format with Black if available
|
||||
if command -v black &> /dev/null; then
|
||||
black "$FILE" 2>/dev/null
|
||||
fi
|
||||
;;
|
||||
go)
|
||||
# Format with gofmt
|
||||
if command -v gofmt &> /dev/null; then
|
||||
gofmt -w "$FILE" 2>/dev/null
|
||||
fi
|
||||
;;
|
||||
rs)
|
||||
# Format with rustfmt
|
||||
if command -v rustfmt &> /dev/null; then
|
||||
rustfmt "$FILE" 2>/dev/null
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
exit 0
|
||||
47
examples/hooks/bash/security-check.sh
Normal file
47
examples/hooks/bash/security-check.sh
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
#!/bin/bash
|
||||
# PreToolUse hook - Block commands containing secrets
|
||||
# Place in: .claude/hooks/security-check.sh
|
||||
# Register in: .claude/settings.json
|
||||
|
||||
INPUT=$(cat)
|
||||
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
|
||||
|
||||
if [[ "$TOOL" == "Bash" ]]; then
|
||||
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
|
||||
|
||||
# Check for common secret patterns
|
||||
PATTERNS=(
|
||||
"password="
|
||||
"PASSWORD="
|
||||
"secret="
|
||||
"SECRET="
|
||||
"api_key="
|
||||
"API_KEY="
|
||||
"apikey="
|
||||
"token="
|
||||
"TOKEN="
|
||||
"aws_access_key"
|
||||
"AWS_ACCESS_KEY"
|
||||
"aws_secret"
|
||||
"AWS_SECRET"
|
||||
"private_key"
|
||||
"PRIVATE_KEY"
|
||||
)
|
||||
|
||||
for PATTERN in "${PATTERNS[@]}"; do
|
||||
if echo "$COMMAND" | grep -qi "$PATTERN"; then
|
||||
echo "{\"decision\": \"block\", \"reason\": \"Potential secret detected: $PATTERN\"}"
|
||||
exit 2
|
||||
fi
|
||||
done
|
||||
|
||||
# Check for hardcoded credentials in common formats
|
||||
# API keys (typically long alphanumeric strings)
|
||||
if echo "$COMMAND" | grep -qE "(sk-[a-zA-Z0-9]{20,}|pk_[a-zA-Z0-9]{20,}|[a-f0-9]{32,})"; then
|
||||
echo "{\"decision\": \"block\", \"reason\": \"Potential API key or hash detected\"}"
|
||||
exit 2
|
||||
fi
|
||||
fi
|
||||
|
||||
# Allow the command
|
||||
exit 0
|
||||
50
examples/hooks/powershell/auto-format.ps1
Normal file
50
examples/hooks/powershell/auto-format.ps1
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# PostToolUse hook - Auto-format files after editing
|
||||
# Place in: .claude\hooks\auto-format.ps1
|
||||
# Register in: .claude\settings.json (with -ExecutionPolicy Bypass)
|
||||
|
||||
$inputJson = [Console]::In.ReadToEnd() | ConvertFrom-Json
|
||||
$tool = $inputJson.tool_name
|
||||
|
||||
# Only run after Write or Edit operations
|
||||
if ($tool -eq "Write" -or $tool -eq "Edit") {
|
||||
$file = $inputJson.tool_input.file_path
|
||||
if (-not $file) {
|
||||
$file = $inputJson.tool_input.path
|
||||
}
|
||||
|
||||
if (-not $file -or $file -eq "null") {
|
||||
exit 0
|
||||
}
|
||||
|
||||
# Get file extension
|
||||
$ext = [System.IO.Path]::GetExtension($file).TrimStart('.')
|
||||
|
||||
switch ($ext) {
|
||||
{ $_ -in @("js", "jsx", "ts", "tsx", "json", "css", "scss", "md", "html", "vue") } {
|
||||
# Format with Prettier if available
|
||||
if (Test-Path "node_modules\.bin\prettier.cmd") {
|
||||
& npx prettier --write $file 2>$null
|
||||
}
|
||||
}
|
||||
"py" {
|
||||
# Format with Black if available
|
||||
if (Get-Command black -ErrorAction SilentlyContinue) {
|
||||
& black $file 2>$null
|
||||
}
|
||||
}
|
||||
"go" {
|
||||
# Format with gofmt
|
||||
if (Get-Command gofmt -ErrorAction SilentlyContinue) {
|
||||
& gofmt -w $file 2>$null
|
||||
}
|
||||
}
|
||||
"rs" {
|
||||
# Format with rustfmt
|
||||
if (Get-Command rustfmt -ErrorAction SilentlyContinue) {
|
||||
& rustfmt $file 2>$null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
exit 0
|
||||
45
examples/hooks/powershell/security-check.ps1
Normal file
45
examples/hooks/powershell/security-check.ps1
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# PreToolUse hook - Block commands containing secrets
|
||||
# Place in: .claude\hooks\security-check.ps1
|
||||
# Register in: .claude\settings.json (with -ExecutionPolicy Bypass)
|
||||
|
||||
$inputJson = [Console]::In.ReadToEnd() | ConvertFrom-Json
|
||||
$tool = $inputJson.tool_name
|
||||
|
||||
if ($tool -eq "Bash") {
|
||||
$command = $inputJson.tool_input.command
|
||||
|
||||
# Check for common secret patterns
|
||||
$patterns = @(
|
||||
"password=",
|
||||
"PASSWORD=",
|
||||
"secret=",
|
||||
"SECRET=",
|
||||
"api_key=",
|
||||
"API_KEY=",
|
||||
"apikey=",
|
||||
"token=",
|
||||
"TOKEN=",
|
||||
"aws_access_key",
|
||||
"AWS_ACCESS_KEY",
|
||||
"aws_secret",
|
||||
"AWS_SECRET",
|
||||
"private_key",
|
||||
"PRIVATE_KEY"
|
||||
)
|
||||
|
||||
foreach ($pattern in $patterns) {
|
||||
if ($command -match [regex]::Escape($pattern)) {
|
||||
Write-Output "{`"decision`": `"block`", `"reason`": `"Potential secret detected: $pattern`"}"
|
||||
exit 2
|
||||
}
|
||||
}
|
||||
|
||||
# Check for hardcoded API keys
|
||||
if ($command -match "(sk-[a-zA-Z0-9]{20,}|pk_[a-zA-Z0-9]{20,}|[a-f0-9]{32,})") {
|
||||
Write-Output "{`"decision`": `"block`", `"reason`": `"Potential API key or hash detected`"}"
|
||||
exit 2
|
||||
}
|
||||
}
|
||||
|
||||
# Allow the command
|
||||
exit 0
|
||||
68
examples/memory/CLAUDE.md.personal-template
Normal file
68
examples/memory/CLAUDE.md.personal-template
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Personal Claude Memory
|
||||
|
||||
> This file provides Claude with your personal preferences.
|
||||
> Place at: ~/.claude/CLAUDE.md (global, applies to all projects).
|
||||
|
||||
## Communication Style
|
||||
|
||||
- Be concise and direct
|
||||
- Use code examples over explanations
|
||||
- Challenge my assumptions when needed
|
||||
- Don't over-explain obvious things
|
||||
|
||||
## Development Preferences
|
||||
|
||||
### Languages & Frameworks
|
||||
- Primary: TypeScript, React, Node.js
|
||||
- Secondary: Python, Go
|
||||
- Preferred test framework: Vitest/Jest
|
||||
|
||||
### Code Style
|
||||
- Prefer functional programming
|
||||
- Use early returns
|
||||
- Keep functions small
|
||||
- Meaningful variable names over comments
|
||||
|
||||
### Tools
|
||||
- Editor: VS Code
|
||||
- Terminal: iTerm2 / Windows Terminal
|
||||
- Version control: Git
|
||||
|
||||
## Workflow Preferences
|
||||
|
||||
### When Writing Code
|
||||
- Always include type definitions
|
||||
- Add error handling
|
||||
- Write tests for critical paths
|
||||
- Use async/await over callbacks
|
||||
|
||||
### When Reviewing
|
||||
- Focus on logic and security first
|
||||
- Style suggestions are secondary
|
||||
- Point out potential edge cases
|
||||
|
||||
### When Debugging
|
||||
- Show me the investigation process
|
||||
- Explain your reasoning
|
||||
- Suggest multiple solutions if applicable
|
||||
|
||||
## Common Shortcuts
|
||||
|
||||
- `cc` → `claude`
|
||||
- `gcm` → `git commit -m`
|
||||
- `gp` → `git push`
|
||||
|
||||
## Pet Peeves
|
||||
|
||||
- Don't add unnecessary comments
|
||||
- Don't over-engineer simple solutions
|
||||
- Don't ignore error handling
|
||||
- Don't use `any` in TypeScript
|
||||
|
||||
## Learning Goals
|
||||
|
||||
- [Current focus areas for learning]
|
||||
|
||||
## Notes
|
||||
|
||||
- [Any other personal notes for Claude]
|
||||
71
examples/memory/CLAUDE.md.project-template
Normal file
71
examples/memory/CLAUDE.md.project-template
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
# Project Memory - [Project Name]
|
||||
|
||||
> This file provides Claude with persistent context about your project.
|
||||
> Place at: ./CLAUDE.md (project root) for team conventions.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Name**: [Project Name]
|
||||
**Type**: [Web app / API / CLI / Library]
|
||||
**Stack**: [e.g., TypeScript, Next.js, Prisma, PostgreSQL]
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # Next.js app router
|
||||
├── components/ # React components
|
||||
├── lib/ # Shared utilities
|
||||
├── services/ # Business logic
|
||||
└── types/ # TypeScript types
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Code Style
|
||||
- Use TypeScript strict mode
|
||||
- Prefer `const` over `let`
|
||||
- Use named exports
|
||||
- Maximum function length: 30 lines
|
||||
|
||||
### Naming
|
||||
- Files: `kebab-case.ts`
|
||||
- Components: `PascalCase.tsx`
|
||||
- Functions: `camelCase`
|
||||
- Constants: `SCREAMING_SNAKE_CASE`
|
||||
|
||||
### Git
|
||||
- Branch format: `type/description` (e.g., `feat/user-auth`)
|
||||
- Commit format: Conventional Commits
|
||||
- PR required for main branch
|
||||
|
||||
## Key Files
|
||||
|
||||
- `@src/lib/db.ts` - Database connection
|
||||
- `@src/services/auth.ts` - Authentication logic
|
||||
- `@docs/api.md` - API documentation
|
||||
|
||||
## Testing
|
||||
|
||||
- Framework: Vitest
|
||||
- Run: `npm test`
|
||||
- Coverage target: 80%
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Development server
|
||||
npm run build # Production build
|
||||
npm run test # Run tests
|
||||
npm run lint # Lint code
|
||||
```
|
||||
|
||||
## Known Issues
|
||||
|
||||
- [Issue description and workaround if any]
|
||||
|
||||
## Team Contacts
|
||||
|
||||
- **Tech Lead**: [Name]
|
||||
- **Backend**: [Name]
|
||||
- **Frontend**: [Name]
|
||||
147
examples/skills/security-checklist.md
Normal file
147
examples/skills/security-checklist.md
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
name: security-checklist
|
||||
description: Comprehensive security checklist for web applications
|
||||
---
|
||||
|
||||
# Security Checklist Skill
|
||||
|
||||
## Quick Security Audit
|
||||
|
||||
### Authentication
|
||||
- [ ] Passwords hashed with bcrypt/argon2 (cost factor >= 10)
|
||||
- [ ] Session tokens are cryptographically random
|
||||
- [ ] JWT tokens have short expiry (15min access, 7d refresh)
|
||||
- [ ] Rate limiting on login endpoints
|
||||
- [ ] Account lockout after failed attempts
|
||||
|
||||
### Authorization
|
||||
- [ ] Every API endpoint checks permissions
|
||||
- [ ] No IDOR (Insecure Direct Object References)
|
||||
- [ ] Role-based access control implemented
|
||||
- [ ] Sensitive operations require re-authentication
|
||||
|
||||
### Input Validation
|
||||
- [ ] All user input validated server-side
|
||||
- [ ] File uploads restricted by type and size
|
||||
- [ ] SQL queries use parameterized statements
|
||||
- [ ] HTML output encoded to prevent XSS
|
||||
|
||||
### Data Protection
|
||||
- [ ] Sensitive data encrypted at rest
|
||||
- [ ] HTTPS enforced everywhere
|
||||
- [ ] Secure cookies (HttpOnly, Secure, SameSite)
|
||||
- [ ] No sensitive data in URLs or logs
|
||||
|
||||
### Headers & CORS
|
||||
- [ ] Content-Security-Policy header set
|
||||
- [ ] X-Content-Type-Options: nosniff
|
||||
- [ ] X-Frame-Options: DENY (or SAMEORIGIN)
|
||||
- [ ] Strict-Transport-Security enabled
|
||||
- [ ] CORS properly restricted
|
||||
|
||||
## Code Patterns
|
||||
|
||||
### SQL Injection Prevention
|
||||
```javascript
|
||||
// VULNERABLE
|
||||
db.query(`SELECT * FROM users WHERE id = ${userId}`);
|
||||
|
||||
// SECURE
|
||||
db.query('SELECT * FROM users WHERE id = $1', [userId]);
|
||||
```
|
||||
|
||||
### XSS Prevention
|
||||
```javascript
|
||||
// VULNERABLE
|
||||
element.innerHTML = userInput;
|
||||
|
||||
// SECURE
|
||||
element.textContent = userInput;
|
||||
|
||||
// SECURE (with sanitization)
|
||||
element.innerHTML = DOMPurify.sanitize(userInput);
|
||||
```
|
||||
|
||||
### CSRF Protection
|
||||
```javascript
|
||||
// Generate token
|
||||
const csrfToken = crypto.randomBytes(32).toString('hex');
|
||||
session.csrfToken = csrfToken;
|
||||
|
||||
// Validate on POST
|
||||
if (req.body.csrf !== session.csrfToken) {
|
||||
throw new ForbiddenError('Invalid CSRF token');
|
||||
}
|
||||
```
|
||||
|
||||
### Secrets Management
|
||||
```javascript
|
||||
// NEVER in code
|
||||
const API_KEY = 'sk-abc123...';
|
||||
|
||||
// Environment variables
|
||||
const API_KEY = process.env.API_KEY;
|
||||
|
||||
// Secrets manager (production)
|
||||
const secret = await secretsManager.getSecret('api-key');
|
||||
```
|
||||
|
||||
## Security Headers Example
|
||||
|
||||
```javascript
|
||||
// Express middleware
|
||||
app.use((req, res, next) => {
|
||||
res.setHeader('X-Content-Type-Options', 'nosniff');
|
||||
res.setHeader('X-Frame-Options', 'DENY');
|
||||
res.setHeader('X-XSS-Protection', '1; mode=block');
|
||||
res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
|
||||
res.setHeader('Content-Security-Policy', "default-src 'self'");
|
||||
next();
|
||||
});
|
||||
```
|
||||
|
||||
## Dependency Security
|
||||
|
||||
```bash
|
||||
# Check for vulnerabilities
|
||||
npm audit
|
||||
|
||||
# Auto-fix what's possible
|
||||
npm audit fix
|
||||
|
||||
# Check outdated packages
|
||||
npm outdated
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
```
|
||||
|
||||
## Logging Security Events
|
||||
|
||||
```javascript
|
||||
// Events to log
|
||||
logger.security({
|
||||
event: 'login_failed',
|
||||
ip: req.ip,
|
||||
email: req.body.email,
|
||||
reason: 'invalid_password',
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
|
||||
// Never log
|
||||
// - Passwords
|
||||
// - Full credit card numbers
|
||||
// - Session tokens
|
||||
// - Personal data (in production)
|
||||
```
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
1. [ ] Run `npm audit` - no critical vulnerabilities
|
||||
2. [ ] All secrets in environment variables
|
||||
3. [ ] Debug mode disabled
|
||||
4. [ ] Error messages don't expose internals
|
||||
5. [ ] HTTPS only (HTTP redirects to HTTPS)
|
||||
6. [ ] Database credentials rotated
|
||||
7. [ ] Logging configured (no sensitive data)
|
||||
8. [ ] Backup strategy tested
|
||||
141
examples/skills/tdd-workflow.md
Normal file
141
examples/skills/tdd-workflow.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
name: tdd-workflow
|
||||
description: Test-Driven Development workflow and best practices
|
||||
---
|
||||
|
||||
# TDD Workflow Skill
|
||||
|
||||
## The TDD Cycle
|
||||
|
||||
```
|
||||
RED → GREEN → REFACTOR
|
||||
↑__________________|
|
||||
```
|
||||
|
||||
### 1. RED: Write a Failing Test
|
||||
- Write the smallest test that fails
|
||||
- Test should fail for the right reason
|
||||
- Ensure the test actually runs
|
||||
|
||||
### 2. GREEN: Make it Pass
|
||||
- Write minimal code to pass the test
|
||||
- Don't optimize yet
|
||||
- It's okay if the code is ugly
|
||||
|
||||
### 3. REFACTOR: Clean Up
|
||||
- Improve code structure
|
||||
- Remove duplication
|
||||
- Keep tests passing
|
||||
|
||||
## TDD Best Practices
|
||||
|
||||
### Test Naming Convention
|
||||
```
|
||||
should_[expected behavior]_when_[condition]
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `should_return_empty_array_when_no_items`
|
||||
- `should_throw_error_when_invalid_input`
|
||||
- `should_calculate_total_when_items_present`
|
||||
|
||||
### Test Structure (AAA)
|
||||
```typescript
|
||||
it('should calculate discount when coupon applied', () => {
|
||||
// Arrange - Set up test data
|
||||
const cart = new Cart();
|
||||
cart.addItem({ price: 100 });
|
||||
const coupon = new Coupon('10OFF', 10);
|
||||
|
||||
// Act - Execute the behavior
|
||||
cart.applyCoupon(coupon);
|
||||
|
||||
// Assert - Verify the result
|
||||
expect(cart.total).toBe(90);
|
||||
});
|
||||
```
|
||||
|
||||
### Test Isolation
|
||||
- Each test should be independent
|
||||
- No shared state between tests
|
||||
- Use `beforeEach` for common setup
|
||||
- Clean up in `afterEach`
|
||||
|
||||
## TDD Workflow Example
|
||||
|
||||
### Feature: Add item to cart
|
||||
|
||||
**Step 1: RED**
|
||||
```typescript
|
||||
describe('Cart', () => {
|
||||
it('should add item to cart', () => {
|
||||
const cart = new Cart();
|
||||
cart.addItem({ id: 1, name: 'Book', price: 29.99 });
|
||||
expect(cart.items).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
```
|
||||
Run test → FAILS (Cart doesn't exist)
|
||||
|
||||
**Step 2: GREEN**
|
||||
```typescript
|
||||
class Cart {
|
||||
items = [];
|
||||
|
||||
addItem(item) {
|
||||
this.items.push(item);
|
||||
}
|
||||
}
|
||||
```
|
||||
Run test → PASSES
|
||||
|
||||
**Step 3: REFACTOR**
|
||||
```typescript
|
||||
class Cart {
|
||||
private _items: CartItem[] = [];
|
||||
|
||||
get items(): ReadonlyArray<CartItem> {
|
||||
return this._items;
|
||||
}
|
||||
|
||||
addItem(item: CartItem): void {
|
||||
this._items.push(item);
|
||||
}
|
||||
}
|
||||
```
|
||||
Run test → Still PASSES
|
||||
|
||||
### Next iteration: Calculate total
|
||||
Repeat the cycle for each new behavior.
|
||||
|
||||
## When to Use TDD
|
||||
|
||||
### Good for TDD
|
||||
- Business logic
|
||||
- Complex algorithms
|
||||
- API endpoints
|
||||
- State management
|
||||
- Utility functions
|
||||
|
||||
### Less Suitable
|
||||
- UI layout (visual testing better)
|
||||
- Database migrations
|
||||
- External integrations (use integration tests)
|
||||
- Exploratory/prototype code
|
||||
|
||||
## Common TDD Mistakes
|
||||
|
||||
1. **Writing too much test** - Start with smallest failing test
|
||||
2. **Writing too much code** - Only enough to pass
|
||||
3. **Skipping refactor** - Technical debt accumulates
|
||||
4. **Testing implementation** - Test behavior, not internals
|
||||
5. **Ignoring failing tests** - Fix or delete, never skip
|
||||
|
||||
## Test Doubles
|
||||
|
||||
| Type | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| Stub | Return fixed data | `jest.fn().mockReturnValue(42)` |
|
||||
| Mock | Verify interactions | `expect(mock).toHaveBeenCalled()` |
|
||||
| Spy | Track calls | `jest.spyOn(obj, 'method')` |
|
||||
| Fake | Simplified implementation | In-memory database |
|
||||
17
llms.txt
17
llms.txt
|
|
@ -53,7 +53,16 @@ claude-code-ultimate-guide/
|
|||
├── english-ultimate-claude-code-guide.md # Complete guide (main content)
|
||||
├── cheatsheet-en.md # 1-page reference
|
||||
├── claude-setup-audit-prompt.md # Setup audit tool
|
||||
├── CONTRIBUTING.md # Contribution guidelines
|
||||
├── CHANGELOG.md # Version history
|
||||
├── llms.txt # This file (for AI indexation)
|
||||
├── examples/ # Ready-to-use templates
|
||||
│ ├── agents/ # Custom AI personas
|
||||
│ ├── skills/ # Knowledge modules
|
||||
│ ├── commands/ # Slash commands
|
||||
│ ├── hooks/ # Event automation (bash + PowerShell)
|
||||
│ ├── config/ # Configuration files
|
||||
│ └── memory/ # CLAUDE.md templates
|
||||
└── *.pdf # Alternative formats
|
||||
```
|
||||
|
||||
|
|
@ -112,9 +121,11 @@ CC BY-SA 4.0 - Free to share and adapt with attribution.
|
|||
## How to Use This Guide
|
||||
|
||||
1. **New to Claude Code?** Start with README.md Quick Start section
|
||||
2. **Want comprehensive learning?** Read english-ultimate-claude-code-guide.md
|
||||
3. **Need daily reference?** Print cheatsheet-en.md
|
||||
4. **Want to audit your setup?** Use claude-setup-audit-prompt.md
|
||||
2. **Choose your path** See Learning Paths in README for audience-specific guides
|
||||
3. **Want comprehensive learning?** Read english-ultimate-claude-code-guide.md
|
||||
4. **Need daily reference?** Print cheatsheet-en.md
|
||||
5. **Want to audit your setup?** Use claude-setup-audit-prompt.md
|
||||
6. **Need templates?** Browse examples/ folder for ready-to-use configs
|
||||
|
||||
## Keywords
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue