feat: 添加Claude代码基础设施展示库初始文件
docs: 新增项目文档和开发指南 chore: 添加.gitignore和LICENSE文件
This commit is contained in:
dzq
parent
e2fffba3ca
commit
bf0a30e0ae
|
|
@ -0,0 +1,51 @@
|
|||
# Dependencies
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
pnpm-debug.log*
|
||||
|
||||
# Environment variables
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
config.ini
|
||||
sentry.ini
|
||||
|
||||
# Logs
|
||||
logs/
|
||||
*.log
|
||||
pm2-logs/
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
*.tsbuildinfo
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Testing
|
||||
coverage/
|
||||
.nyc_output/
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
*.tmp
|
||||
|
||||
# Database
|
||||
*.sqlite
|
||||
*.db
|
||||
|
||||
# Prisma
|
||||
.env
|
||||
prisma/.env
|
||||
|
|
@ -0,0 +1,883 @@
|
|||
# Claude Integration Guide
|
||||
|
||||
**FOR CLAUDE CODE:** When a user asks you to integrate components from this showcase repository into their project, follow these instructions carefully.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This repository is a **reference library** of Claude Code infrastructure components. Users will ask you to help integrate specific pieces into their projects. Your role is to:
|
||||
|
||||
1. **Ask clarifying questions** about their project structure
|
||||
2. **Copy the appropriate files**
|
||||
3. **Customize configurations** for their setup
|
||||
4. **Verify the integration** works correctly
|
||||
|
||||
**Key Principle:** ALWAYS ask before assuming project structure. What works for one project won't work for another.
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack Compatibility Check
|
||||
|
||||
**CRITICAL:** Before integrating a skill, verify the user's tech stack matches the skill requirements.
|
||||
|
||||
### Frontend Skills
|
||||
|
||||
**frontend-dev-guidelines requires:**
|
||||
- React (18+)
|
||||
- MUI v7
|
||||
- TanStack Query
|
||||
- TanStack Router
|
||||
- TypeScript
|
||||
|
||||
**Before integrating, ask:**
|
||||
"Do you use React with MUI v7?"
|
||||
|
||||
**If NO:**
|
||||
```
|
||||
The frontend-dev-guidelines skill is designed specifically for React + MUI v7. I can:
|
||||
1. Help you create a similar skill adapted for [their stack] using this as a template
|
||||
2. Extract the framework-agnostic patterns (file organization, performance, etc.)
|
||||
3. Skip this skill if not relevant
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
### Backend Skills
|
||||
|
||||
**backend-dev-guidelines requires:**
|
||||
- Node.js/Express
|
||||
- TypeScript
|
||||
- Prisma ORM
|
||||
- Sentry
|
||||
|
||||
**Before integrating, ask:**
|
||||
"Do you use Node.js with Express and Prisma?"
|
||||
|
||||
**If NO:**
|
||||
```
|
||||
The backend-dev-guidelines skill is designed for Express/Prisma. I can:
|
||||
1. Help you create similar guidelines adapted for [their stack] using this as a template
|
||||
2. Extract the architecture patterns (layered architecture works for any framework)
|
||||
3. Skip this skill
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
### Skills That Are Tech-Agnostic
|
||||
|
||||
These work for ANY tech stack:
|
||||
- ✅ **skill-developer** - Meta-skill, no tech requirements
|
||||
- ✅ **route-tester** - Only requires JWT cookie auth (framework agnostic)
|
||||
- ✅ **error-tracking** - Sentry works with most stacks
|
||||
|
||||
---
|
||||
|
||||
## General Integration Pattern
|
||||
|
||||
When user says: **"Add [component] to my project"**
|
||||
|
||||
1. Identify component type (skill/hook/agent/command)
|
||||
2. **CHECK TECH STACK COMPATIBILITY** (for frontend/backend skills)
|
||||
3. Ask about their project structure
|
||||
4. Copy files OR adapt for their stack
|
||||
5. Customize for their setup
|
||||
6. Verify integration
|
||||
7. Provide next steps
|
||||
|
||||
---
|
||||
|
||||
## Integrating Skills
|
||||
|
||||
### Step-by-Step Process
|
||||
|
||||
**When user requests a skill** (e.g., "add backend-dev-guidelines"):
|
||||
|
||||
#### 1. Understand Their Project
|
||||
|
||||
**ASK THESE QUESTIONS:**
|
||||
- "What's your project structure? Single app, monorepo, or multi-service?"
|
||||
- "Where is your [backend/frontend] code located?"
|
||||
- "What frameworks/technologies do you use?"
|
||||
|
||||
#### 2. Copy the Skill
|
||||
|
||||
```bash
|
||||
cp -r /path/to/showcase/.claude/skills/[skill-name] \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/
|
||||
```
|
||||
|
||||
#### 3. Handle skill-rules.json
|
||||
|
||||
**Check if it exists:**
|
||||
```bash
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json
|
||||
```
|
||||
|
||||
**If NO (doesn't exist):**
|
||||
- Copy the template from showcase
|
||||
- Remove skills user doesn't want
|
||||
- Customize for their project
|
||||
|
||||
**If YES (exists):**
|
||||
- Read their current skill-rules.json
|
||||
- Add the new skill entry
|
||||
- Merge carefully to avoid breaking existing skills
|
||||
|
||||
#### 4. Customize Path Patterns
|
||||
|
||||
**CRITICAL:** Update `pathPatterns` in skill-rules.json to match THEIR structure:
|
||||
|
||||
**Example - User has monorepo:**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"packages/api/src/**/*.ts",
|
||||
"packages/server/src/**/*.ts",
|
||||
"apps/backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example - User has single backend:**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Safe Generic Patterns** (when unsure):
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"**/*.ts", // All TypeScript files
|
||||
"src/**/*.ts", // Common src directory
|
||||
"backend/**/*.ts" // Common backend directory
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Verify Integration
|
||||
|
||||
```bash
|
||||
# Check skill was copied
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/skills/[skill-name]
|
||||
|
||||
# Validate skill-rules.json syntax
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
```
|
||||
|
||||
**Tell user:** "Try editing a file in [their-backend-path] and the skill should activate."
|
||||
|
||||
---
|
||||
|
||||
### Skill-Specific Notes
|
||||
|
||||
#### backend-dev-guidelines
|
||||
- **Tech Requirements:** Node.js/Express, Prisma, TypeScript, Sentry
|
||||
- **Ask:** "Do you use Express with Prisma?" "Where's your backend code?"
|
||||
- **If different stack:** Offer to adapt using this as template
|
||||
- **Customize:** pathPatterns
|
||||
- **Example paths:** `api/`, `server/`, `backend/`, `services/*/src/`
|
||||
- **Adaptation tip:** Architecture patterns (Routes→Controllers→Services) transfer to most frameworks
|
||||
|
||||
#### frontend-dev-guidelines
|
||||
- **Tech Requirements:** React 18+, MUI v7, TanStack Query/Router, TypeScript
|
||||
- **Ask:** "Do you use React with MUI v7?" "Where's your frontend code?"
|
||||
- **If different stack:** Offer to create adapted version (Vue, Angular, etc.)
|
||||
- **Customize:** pathPatterns + all framework-specific examples
|
||||
- **Example paths:** `frontend/`, `client/`, `web/`, `apps/web/src/`
|
||||
- **Adaptation tip:** File organization and performance patterns transfer, component code doesn't
|
||||
|
||||
#### route-tester
|
||||
- **Tech Requirements:** JWT cookie-based authentication (framework agnostic)
|
||||
- **Ask:** "Do you use JWT cookie-based authentication?"
|
||||
- **If NO:** "This skill is designed for JWT cookies. Want me to adapt it for [their auth type] or skip it?"
|
||||
- **Customize:** Service URLs, auth patterns
|
||||
- **Works with:** Any backend framework using JWT cookies
|
||||
|
||||
#### error-tracking
|
||||
- **Tech Requirements:** Sentry (works with most backends)
|
||||
- **Ask:** "Do you use Sentry?" "Where's your backend code?"
|
||||
- **If NO Sentry:** "Want to use this as template for [their error tracking]?"
|
||||
- **Customize:** pathPatterns
|
||||
- **Adaptation tip:** Error tracking philosophy transfers to other tools (Rollbar, Bugsnag, etc.)
|
||||
|
||||
#### skill-developer
|
||||
- **Tech Requirements:** None!
|
||||
- **Copy as-is** - meta-skill, fully generic, teaches skill creation for ANY tech stack
|
||||
|
||||
---
|
||||
|
||||
## Adapting Skills for Different Tech Stacks
|
||||
|
||||
When user's tech stack differs from skill requirements, you have options:
|
||||
|
||||
### Option 1: Adapt Existing Skill (Recommended)
|
||||
|
||||
**When to use:** User wants similar guidelines but for different tech
|
||||
|
||||
**Process:**
|
||||
1. **Copy the skill as a starting point:**
|
||||
```bash
|
||||
cp -r showcase/.claude/skills/frontend-dev-guidelines \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines
|
||||
```
|
||||
|
||||
2. **Identify what needs changing:**
|
||||
- Framework-specific code examples (React → Vue)
|
||||
- Library APIs (MUI → Vuetify/PrimeVue)
|
||||
- Import statements
|
||||
- Component patterns
|
||||
|
||||
3. **Keep what transfers:**
|
||||
- File organization principles
|
||||
- Performance optimization strategies
|
||||
- TypeScript standards
|
||||
- General best practices
|
||||
|
||||
4. **Replace examples systematically:**
|
||||
- Ask user for equivalent patterns in their stack
|
||||
- Update code examples to their framework
|
||||
- Keep the overall structure and sections
|
||||
|
||||
5. **Update skill name and triggers:**
|
||||
- Rename skill appropriately
|
||||
- Update skill-rules.json triggers for their stack
|
||||
- Test activation
|
||||
|
||||
**Example - Adapting frontend-dev-guidelines for Vue:**
|
||||
```
|
||||
I'll create vue-dev-guidelines based on the React skill structure:
|
||||
- Replace React.FC → Vue defineComponent
|
||||
- Replace useSuspenseQuery → Vue composables
|
||||
- Replace MUI components → [their component library]
|
||||
- Keep: File organization, performance patterns, TypeScript guidelines
|
||||
|
||||
This will take a few minutes. Sound good?
|
||||
```
|
||||
|
||||
### Option 2: Extract Framework-Agnostic Patterns
|
||||
|
||||
**When to use:** Stacks are very different, but core principles apply
|
||||
|
||||
**Process:**
|
||||
1. Read through the existing skill
|
||||
2. Identify framework-agnostic patterns:
|
||||
- Layered architecture (backend)
|
||||
- File organization strategies
|
||||
- Performance optimization principles
|
||||
- Testing strategies
|
||||
- Error handling philosophy
|
||||
|
||||
3. Create new skill with just those patterns
|
||||
4. User can add framework-specific examples later
|
||||
|
||||
**Example:**
|
||||
```
|
||||
The backend-dev-guidelines uses Express, but the layered architecture
|
||||
(Routes → Controllers → Services → Repositories) works for Django too.
|
||||
|
||||
I can create a skill with:
|
||||
- Layered architecture pattern
|
||||
- Separation of concerns principles
|
||||
- Error handling best practices
|
||||
- Testing strategies
|
||||
|
||||
Then you can add Django-specific examples as you establish patterns.
|
||||
```
|
||||
|
||||
### Option 3: Use as Reference Only
|
||||
|
||||
**When to use:** Too different to adapt, but user wants inspiration
|
||||
|
||||
**Process:**
|
||||
1. User browses the existing skill
|
||||
2. You help create a new skill from scratch
|
||||
3. Use existing skill's structure as a template
|
||||
4. Follow modular pattern (main + resource files)
|
||||
|
||||
### What Usually Transfers Across Tech Stacks
|
||||
|
||||
**Architecture & Organization:**
|
||||
- ✅ Layered architecture (Routes/Controllers/Services pattern)
|
||||
- ✅ Separation of concerns
|
||||
- ✅ File organization strategies (features/ pattern)
|
||||
- ✅ Progressive disclosure (main + resource files)
|
||||
- ✅ Repository pattern for data access
|
||||
|
||||
**Development Practices:**
|
||||
- ✅ Error handling philosophy
|
||||
- ✅ Input validation importance
|
||||
- ✅ Testing strategies
|
||||
- ✅ Performance optimization principles
|
||||
- ✅ TypeScript best practices
|
||||
|
||||
**Framework-Specific Code:**
|
||||
- ❌ React hooks → Don't transfer to Vue/Angular
|
||||
- ❌ MUI components → Different component libraries
|
||||
- ❌ Prisma queries → Different ORM syntax
|
||||
- ❌ Express middleware → Different framework patterns
|
||||
- ❌ Routing implementations → Framework-specific
|
||||
|
||||
### When to Recommend Adaptation vs Skipping
|
||||
|
||||
**Recommend adaptation if:**
|
||||
- User wants similar guidelines for their stack
|
||||
- Core patterns apply (layered architecture, etc.)
|
||||
- User has time to help with framework-specific examples
|
||||
|
||||
**Recommend skipping if:**
|
||||
- Stacks are completely different
|
||||
- User doesn't need those patterns
|
||||
- Would take too long to adapt
|
||||
- User prefers creating from scratch
|
||||
|
||||
---
|
||||
|
||||
## Integrating Hooks
|
||||
|
||||
### Essential Hooks (Always Safe to Copy)
|
||||
|
||||
#### skill-activation-prompt (UserPromptSubmit)
|
||||
|
||||
**Purpose:** Auto-suggests skills based on user prompts
|
||||
|
||||
**Integration (NO customization needed):**
|
||||
|
||||
```bash
|
||||
# Copy both files
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.ts \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# Make executable
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh
|
||||
|
||||
# Install dependencies if needed
|
||||
if [ -f "showcase/.claude/hooks/package.json" ]; then
|
||||
cp showcase/.claude/hooks/package.json \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cd $CLAUDE_PROJECT_DIR/.claude/hooks && npm install
|
||||
fi
|
||||
```
|
||||
|
||||
**Add to settings.json:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**This hook is FULLY GENERIC** - works anywhere, no customization needed!
|
||||
|
||||
#### post-tool-use-tracker (PostToolUse)
|
||||
|
||||
**Purpose:** Tracks file changes for context management
|
||||
|
||||
**Integration (NO customization needed):**
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp showcase/.claude/hooks/post-tool-use-tracker.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# Make executable
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh
|
||||
```
|
||||
|
||||
**Add to settings.json:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**This hook is FULLY GENERIC** - auto-detects project structure!
|
||||
|
||||
---
|
||||
|
||||
### Optional Hooks (Require Heavy Customization)
|
||||
|
||||
#### tsc-check.sh and trigger-build-resolver.sh (Stop hooks)
|
||||
|
||||
⚠️ **WARNING:** These hooks are configured for a specific multi-service monorepo structure.
|
||||
|
||||
**Before integrating, ask:**
|
||||
1. "Do you have a monorepo with multiple TypeScript services?"
|
||||
2. "What are your service directory names?"
|
||||
3. "Where are your tsconfig.json files located?"
|
||||
|
||||
**For SIMPLE projects (single service):**
|
||||
- **RECOMMEND SKIPPING** these hooks
|
||||
- They're overkill for single-service projects
|
||||
- User can run `tsc --noEmit` manually instead
|
||||
|
||||
**For COMPLEX projects (multi-service monorepo):**
|
||||
|
||||
1. Copy the files
|
||||
2. **MUST EDIT** tsc-check.sh - find this section:
|
||||
```bash
|
||||
case "$repo" in
|
||||
email|exports|form|frontend|projects|uploads|users|utilities|events|database)
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
3. Replace with USER'S actual service names:
|
||||
```bash
|
||||
case "$repo" in
|
||||
api|web|auth|payments|notifications) # ← User's services
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
4. Test manually before adding to settings.json:
|
||||
```bash
|
||||
./.claude/hooks/tsc-check.sh
|
||||
```
|
||||
|
||||
**IMPORTANT:** If this hook fails, it will block Stop events. Only add if you're sure it works for their setup.
|
||||
|
||||
---
|
||||
|
||||
## Integrating Agents
|
||||
|
||||
**Agents are STANDALONE** - easiest to integrate!
|
||||
|
||||
### Standard Agent Integration
|
||||
|
||||
```bash
|
||||
# Copy the agent file
|
||||
cp showcase/.claude/agents/[agent-name].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/
|
||||
```
|
||||
|
||||
**That's it!** Agents work immediately, no configuration needed.
|
||||
|
||||
### Check for Hardcoded Paths
|
||||
|
||||
Some agents may reference paths. **Before copying, read the agent file and check for:**
|
||||
|
||||
- `~/git/old-project/` → Should be `$CLAUDE_PROJECT_DIR` or `.`
|
||||
- `/root/git/project/` → Should be `$CLAUDE_PROJECT_DIR` or `.`
|
||||
- Hardcoded screenshot paths → Ask user where they want screenshots
|
||||
|
||||
**If found, update them:**
|
||||
```bash
|
||||
sed -i 's|~/git/old-project/|.|g' $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
sed -i 's|/root/git/.*PROJECT.*DIR|$CLAUDE_PROJECT_DIR|g' \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
```
|
||||
|
||||
### Agent-Specific Notes
|
||||
|
||||
**auth-route-tester / auth-route-debugger:**
|
||||
- Requires JWT cookie-based authentication in user's project
|
||||
- Ask: "Do you use JWT cookies for auth?"
|
||||
- If NO: "These agents are for JWT cookie auth. Skip them or want me to adapt?"
|
||||
|
||||
**frontend-error-fixer:**
|
||||
- May reference screenshot paths
|
||||
- Ask: "Where should screenshots be saved?"
|
||||
|
||||
**All other agents:**
|
||||
- Copy as-is, they're fully generic
|
||||
|
||||
---
|
||||
|
||||
## Integrating Slash Commands
|
||||
|
||||
```bash
|
||||
# Copy command file
|
||||
cp showcase/.claude/commands/[command].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/commands/
|
||||
```
|
||||
|
||||
### Customize Paths
|
||||
|
||||
Commands may reference dev docs paths. **Check and update:**
|
||||
|
||||
**dev-docs and dev-docs-update:**
|
||||
- Look for `dev/active/` path references
|
||||
- Ask: "Where do you want dev documentation stored?"
|
||||
- Update paths in the command files
|
||||
|
||||
**route-research-for-testing:**
|
||||
- May reference service paths
|
||||
- Ask about their API structure
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns & Best Practices
|
||||
|
||||
### Pattern: Asking About Project Structure
|
||||
|
||||
**DON'T assume:**
|
||||
- ❌ "I'll add this for your blog-api service"
|
||||
- ❌ "Configuring for your frontend directory"
|
||||
|
||||
**DO ask:**
|
||||
- ✅ "What's your project structure? Monorepo or single app?"
|
||||
- ✅ "Where is your backend code located?"
|
||||
- ✅ "Do you use workspaces or have multiple services?"
|
||||
|
||||
### Pattern: Customizing skill-rules.json
|
||||
|
||||
**User has monorepo with workspaces:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"packages/*/src/**/*.ts",
|
||||
"apps/*/src/**/*.tsx"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**User has Nx monorepo:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"apps/api/src/**/*.ts",
|
||||
"libs/*/src/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**User has simple structure:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern: settings.json Integration
|
||||
|
||||
**NEVER copy the showcase settings.json directly!**
|
||||
|
||||
Instead, **extract and merge** the sections they need:
|
||||
|
||||
1. Read their existing settings.json
|
||||
2. Add the hook configurations they want
|
||||
3. Preserve their existing config
|
||||
|
||||
**Example merge:**
|
||||
```json
|
||||
{
|
||||
// ... their existing config ...
|
||||
"hooks": {
|
||||
// ... their existing hooks ...
|
||||
"UserPromptSubmit": [ // ← Add this section
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After integration, **verify these items:**
|
||||
|
||||
```bash
|
||||
# 1. Hooks are executable
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh
|
||||
# Should show: -rwxr-xr-x
|
||||
|
||||
# 2. skill-rules.json is valid JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
# Should parse without errors
|
||||
|
||||
# 3. Hook dependencies installed (if TypeScript hooks)
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/hooks/node_modules/
|
||||
# Should show packages if package.json exists
|
||||
|
||||
# 4. Settings.json is valid JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | jq .
|
||||
# Should parse without errors
|
||||
```
|
||||
|
||||
**Then ask user to test:**
|
||||
- "Try editing a file in [relevant-path] - the skill should activate"
|
||||
- "Try asking me a question about [topic] - I should suggest the skill"
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ DON'T: Copy settings.json as-is
|
||||
**Why:** The Stop hooks reference non-existent services
|
||||
**DO:** Extract only UserPromptSubmit and PostToolUse sections
|
||||
|
||||
### ❌ DON'T: Keep example service names
|
||||
**Why:** User doesn't have blog-api, auth-service, etc.
|
||||
**DO:** Ask about their actual structure and update
|
||||
|
||||
### ❌ DON'T: Skip making hooks executable
|
||||
**Why:** Hooks won't run without execute permission
|
||||
**DO:** Always `chmod +x` after copying
|
||||
|
||||
### ❌ DON'T: Assume monorepo structure
|
||||
**Why:** Most projects are single-service
|
||||
**DO:** Ask first, then customize
|
||||
|
||||
### ❌ DON'T: Add all skills at once
|
||||
**Why:** Overwhelming and may not all be relevant
|
||||
**DO:** Ask which skills are relevant to their work
|
||||
|
||||
### ❌ DON'T: Copy Stop hooks without testing
|
||||
**Why:** They can block the Stop event if they fail
|
||||
**DO:** Test manually first, only add if working
|
||||
|
||||
---
|
||||
|
||||
## Example Integration Conversations
|
||||
|
||||
### Example 1: Adding Backend Skill
|
||||
|
||||
**User:** "Add the backend-dev-guidelines skill to my project"
|
||||
|
||||
**Claude should respond:**
|
||||
```
|
||||
I'll add the backend-dev-guidelines skill. First, I need to understand
|
||||
your project structure:
|
||||
|
||||
1. Is this a monorepo with multiple services, or a single backend application?
|
||||
2. Where is your backend code located? (e.g., src/, backend/, server/)
|
||||
3. Do you use Express.js?
|
||||
```
|
||||
|
||||
**User:** "Single app, code is in src/api/, yes we use Express"
|
||||
|
||||
**Claude should:**
|
||||
1. Copy the skill directory
|
||||
2. Update skill-rules.json with pathPattern: `"src/api/**/*.ts"`
|
||||
3. Verify it's copied correctly
|
||||
4. Respond:
|
||||
```
|
||||
✅ Added backend-dev-guidelines skill!
|
||||
|
||||
Configuration:
|
||||
- Skill triggers when editing files in src/api/
|
||||
- Activated by keywords like "controller", "service", "route", "API"
|
||||
|
||||
Try it: Edit a file in src/api/ and you should see the skill suggestion.
|
||||
```
|
||||
|
||||
### Example 2: Setting Up Hooks
|
||||
|
||||
**User:** "Set up the skill activation hooks"
|
||||
|
||||
**Claude should respond:**
|
||||
```
|
||||
I'll set up the skill auto-activation system. This requires two hooks:
|
||||
1. skill-activation-prompt - Suggests skills based on your prompts
|
||||
2. post-tool-use-tracker - Tracks file changes
|
||||
|
||||
Do you have a .claude/settings.json file already, or should I create one?
|
||||
```
|
||||
|
||||
**User:** "I have settings.json already"
|
||||
|
||||
**Claude should:**
|
||||
1. Read their settings.json
|
||||
2. Copy both hook files
|
||||
3. Run npm install in hooks directory
|
||||
4. Add hook configurations to their settings.json (preserving existing config)
|
||||
5. Make hooks executable
|
||||
6. Respond:
|
||||
```
|
||||
✅ Skill activation hooks installed!
|
||||
|
||||
What I did:
|
||||
- Copied skill-activation-prompt hook
|
||||
- Copied post-tool-use-tracker hook
|
||||
- Installed dependencies
|
||||
- Added to your settings.json
|
||||
|
||||
Test it: Ask me "help with backend development" and I should suggest
|
||||
the backend-dev-guidelines skill.
|
||||
```
|
||||
|
||||
### Example 3: Adding Agent
|
||||
|
||||
**User:** "Add the code-architecture-reviewer agent"
|
||||
|
||||
**Claude should:**
|
||||
```
|
||||
The code-architecture-reviewer agent reviews code for architectural issues
|
||||
and best practices. This agent works standalone, no configuration needed.
|
||||
|
||||
I'll copy it to your .claude/agents/ directory now.
|
||||
```
|
||||
|
||||
**Then:**
|
||||
1. Copy the agent file
|
||||
2. Respond:
|
||||
```
|
||||
✅ Added code-architecture-reviewer agent!
|
||||
|
||||
Use it by running the Task tool with:
|
||||
- subagent_type: "code-architecture-reviewer"
|
||||
- prompt: Description of code to review
|
||||
|
||||
The agent will review your code and provide architectural feedback.
|
||||
```
|
||||
|
||||
### Example 3: Tech Stack Mismatch
|
||||
|
||||
**User:** "Add the frontend-dev-guidelines skill to my Vue project"
|
||||
|
||||
**Claude should:**
|
||||
```
|
||||
I see you're using Vue. The frontend-dev-guidelines skill is specifically
|
||||
designed for React + MUI v7. I have a few options:
|
||||
|
||||
Option 1 (Recommended): I can create a vue-dev-guidelines skill using the
|
||||
React skill as a template. I'll adapt:
|
||||
- Component patterns for Vue (Composition API, defineComponent)
|
||||
- Replace MUI examples with your component library
|
||||
- Adapt data fetching for Vue patterns
|
||||
- Keep: File organization, performance principles, TypeScript standards
|
||||
|
||||
Option 2: Extract only the framework-agnostic patterns (file organization,
|
||||
performance, testing) without React-specific code.
|
||||
|
||||
Option 3: Skip it and help you create Vue guidelines from scratch.
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
**User:** "Option 1 sounds good, I use Vuetify"
|
||||
|
||||
**Claude should:**
|
||||
1. Copy frontend-dev-guidelines as vue-dev-guidelines
|
||||
2. Go through each resource file
|
||||
3. Replace React patterns with Vue Composition API
|
||||
4. Replace MUI components with Vuetify
|
||||
5. Update skill-rules.json with Vue-specific triggers (.vue files)
|
||||
6. Respond:
|
||||
```
|
||||
✅ Created vue-dev-guidelines skill adapted for Vue 3 + Vuetify!
|
||||
|
||||
What I changed:
|
||||
- React.FC components → Vue defineComponent
|
||||
- MUI v7 examples → Vuetify components
|
||||
- TanStack Query → Your data fetching approach
|
||||
- File patterns → .vue files
|
||||
|
||||
What I kept:
|
||||
- File organization (features/ pattern)
|
||||
- Performance optimization strategies
|
||||
- TypeScript standards
|
||||
- Loading/error state principles
|
||||
|
||||
Try editing a .vue file - the skill should activate.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Tables
|
||||
|
||||
### What Needs Customization?
|
||||
|
||||
| Component | Tech Requirements | Customization | What to Ask |
|
||||
|-----------|------------------|--------------|-------------|
|
||||
| **skill-developer** | None | ✅ None | Copy as-is |
|
||||
| **backend-dev-guidelines** | Express/Prisma/Node | ⚠️ Paths + tech check | "Use Express/Prisma?" "Where's backend?" |
|
||||
| **frontend-dev-guidelines** | React/MUI v7 | ⚠️⚠️ Paths + framework | "Use React/MUI v7?" "Where's frontend?" |
|
||||
| **route-tester** | JWT cookies | ⚠️ Auth + paths | "JWT cookie auth?" |
|
||||
| **error-tracking** | Sentry | ⚠️ Paths | "Use Sentry?" "Where's backend?" |
|
||||
| **skill-activation-prompt** | ✅ None | Copy as-is |
|
||||
| **post-tool-use-tracker** | ✅ None | Copy as-is |
|
||||
| **tsc-check** | ⚠️⚠️⚠️ Heavy | "Monorepo or single service?" |
|
||||
| **All agents** | ✅ Minimal | Check paths |
|
||||
| **All commands** | ⚠️ Paths | "Where for dev docs?" |
|
||||
|
||||
### When to Recommend Skipping
|
||||
|
||||
| Component | Skip If... |
|
||||
|-----------|-----------|
|
||||
| **tsc-check hooks** | Single-service project or different build setup |
|
||||
| **route-tester** | Not using JWT cookie authentication |
|
||||
| **frontend-dev-guidelines** | Not using React + MUI |
|
||||
| **auth agents** | Not using JWT cookie auth |
|
||||
|
||||
---
|
||||
|
||||
## Final Tips for Claude
|
||||
|
||||
**When user says "add everything":**
|
||||
- Start with essentials: skill-activation hooks + 1-2 relevant skills
|
||||
- Don't overwhelm them with all 5 skills + 10 agents
|
||||
- Ask what they actually need
|
||||
|
||||
**When something doesn't work:**
|
||||
- Check verification checklist
|
||||
- Verify paths match their structure
|
||||
- Test hooks manually
|
||||
- Check for JSON syntax errors
|
||||
|
||||
**When user is unsure:**
|
||||
- Recommend starting with just skill-activation hooks
|
||||
- Add backend OR frontend skill (whichever they use)
|
||||
- Add more later as needed
|
||||
|
||||
**Always explain what you're doing:**
|
||||
- Show the commands you're running
|
||||
- Explain why you're asking questions
|
||||
- Provide clear next steps after integration
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This is a reference library, not a working application. Your job is to help users cherry-pick and adapt components for THEIR specific project structure.
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2025 Claude Code Infrastructure Contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -0,0 +1,360 @@
|
|||
# Claude Code Infrastructure Showcase
|
||||
|
||||
**A curated reference library of production-tested Claude Code infrastructure.**
|
||||
|
||||
Born from 6 months of real-world use managing a complex TypeScript microservices project, this showcase provides the patterns and systems that solved the "skills don't activate automatically" problem and scaled Claude Code for enterprise development.
|
||||
|
||||
> **This is NOT a working application** - it's a reference library. Copy what you need into your own projects.
|
||||
|
||||
---
|
||||
|
||||
## What's Inside
|
||||
|
||||
**Production-tested infrastructure for:**
|
||||
- ✅ **Auto-activating skills** via hooks
|
||||
- ✅ **Modular skill pattern** (500-line rule with progressive disclosure)
|
||||
- ✅ **Specialized agents** for complex tasks
|
||||
- ✅ **Dev docs system** that survives context resets
|
||||
- ✅ **Comprehensive examples** using generic blog domain
|
||||
|
||||
**Time investment to build:** 6 months of iteration
|
||||
**Time to integrate into your project:** 15-30 minutes
|
||||
|
||||
---
|
||||
|
||||
## Quick Start - Pick Your Path
|
||||
|
||||
### 🤖 Using Claude Code to Integrate?
|
||||
|
||||
**Claude:** Read [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) for step-by-step integration instructions tailored for AI-assisted setup.
|
||||
|
||||
### 🎯 I want skill auto-activation
|
||||
|
||||
**The breakthrough feature:** Skills that actually activate when you need them.
|
||||
|
||||
**What you need:**
|
||||
1. The skill-activation hooks (2 files)
|
||||
2. A skill or two relevant to your work
|
||||
3. 15 minutes
|
||||
|
||||
**👉 [Setup Guide: .claude/hooks/README.md](.claude/hooks/README.md)**
|
||||
|
||||
### 📚 I want to add ONE skill
|
||||
|
||||
Browse the [skills catalog](.claude/skills/) and copy what you need.
|
||||
|
||||
**Available:**
|
||||
- **backend-dev-guidelines** - Node.js/Express/TypeScript patterns
|
||||
- **frontend-dev-guidelines** - React/TypeScript/MUI v7 patterns
|
||||
- **skill-developer** - Meta-skill for creating skills
|
||||
- **route-tester** - Test authenticated API routes
|
||||
- **error-tracking** - Sentry integration patterns
|
||||
|
||||
**👉 [Skills Guide: .claude/skills/README.md](.claude/skills/README.md)**
|
||||
|
||||
### 🤖 I want specialized agents
|
||||
|
||||
10 production-tested agents for complex tasks:
|
||||
- Code architecture review
|
||||
- Refactoring assistance
|
||||
- Documentation generation
|
||||
- Error debugging
|
||||
- And more...
|
||||
|
||||
**👉 [Agents Guide: .claude/agents/README.md](.claude/agents/README.md)**
|
||||
|
||||
---
|
||||
|
||||
## What Makes This Different?
|
||||
|
||||
### The Auto-Activation Breakthrough
|
||||
|
||||
**Problem:** Claude Code skills just sit there. You have to remember to use them.
|
||||
|
||||
**Solution:** UserPromptSubmit hook that:
|
||||
- Analyzes your prompts
|
||||
- Checks file context
|
||||
- Automatically suggests relevant skills
|
||||
- Works via `skill-rules.json` configuration
|
||||
|
||||
**Result:** Skills activate when you need them, not when you remember them.
|
||||
|
||||
### Production-Tested Patterns
|
||||
|
||||
These aren't theoretical examples - they're extracted from:
|
||||
- ✅ 6 microservices in production
|
||||
- ✅ 50,000+ lines of TypeScript
|
||||
- ✅ React frontend with complex data grids
|
||||
- ✅ Sophisticated workflow engine
|
||||
- ✅ 6 months of daily Claude Code use
|
||||
|
||||
The patterns work because they solved real problems.
|
||||
|
||||
### Modular Skills (500-Line Rule)
|
||||
|
||||
Large skills hit context limits. The solution:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
SKILL.md # <500 lines, high-level guide
|
||||
resources/
|
||||
topic-1.md # <500 lines each
|
||||
topic-2.md
|
||||
topic-3.md
|
||||
```
|
||||
|
||||
**Progressive disclosure:** Claude loads main skill first, loads resources only when needed.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── skills/ # 5 production skills
|
||||
│ ├── backend-dev-guidelines/ (12 resource files)
|
||||
│ ├── frontend-dev-guidelines/ (11 resource files)
|
||||
│ ├── skill-developer/ (7 resource files)
|
||||
│ ├── route-tester/
|
||||
│ ├── error-tracking/
|
||||
│ └── skill-rules.json # Skill activation configuration
|
||||
├── hooks/ # 6 hooks for automation
|
||||
│ ├── skill-activation-prompt.* (ESSENTIAL)
|
||||
│ ├── post-tool-use-tracker.sh (ESSENTIAL)
|
||||
│ ├── tsc-check.sh (optional, needs customization)
|
||||
│ └── trigger-build-resolver.sh (optional)
|
||||
├── agents/ # 10 specialized agents
|
||||
│ ├── code-architecture-reviewer.md
|
||||
│ ├── refactor-planner.md
|
||||
│ ├── frontend-error-fixer.md
|
||||
│ └── ... 7 more
|
||||
└── commands/ # 3 slash commands
|
||||
├── dev-docs.md
|
||||
└── ...
|
||||
|
||||
dev/
|
||||
└── active/ # Dev docs pattern examples
|
||||
└── public-infrastructure-repo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Catalog
|
||||
|
||||
### 🎨 Skills (5)
|
||||
|
||||
| Skill | Lines | Purpose | Best For |
|
||||
|-------|-------|---------|----------|
|
||||
| [**skill-developer**](.claude/skills/skill-developer/) | 426 | Creating and managing skills | Meta-development |
|
||||
| [**backend-dev-guidelines**](.claude/skills/backend-dev-guidelines/) | 304 | Express/Prisma/Sentry patterns | Backend APIs |
|
||||
| [**frontend-dev-guidelines**](.claude/skills/frontend-dev-guidelines/) | 398 | React/MUI v7/TypeScript | React frontends |
|
||||
| [**route-tester**](.claude/skills/route-tester/) | 389 | Testing authenticated routes | API testing |
|
||||
| [**error-tracking**](.claude/skills/error-tracking/) | ~250 | Sentry integration | Error monitoring |
|
||||
|
||||
**All skills follow the modular pattern** - main file + resource files for progressive disclosure.
|
||||
|
||||
**👉 [How to integrate skills →](.claude/skills/README.md)**
|
||||
|
||||
### 🪝 Hooks (6)
|
||||
|
||||
| Hook | Type | Essential? | Customization |
|
||||
|------|------|-----------|---------------|
|
||||
| skill-activation-prompt | UserPromptSubmit | ✅ YES | ✅ None needed |
|
||||
| post-tool-use-tracker | PostToolUse | ✅ YES | ✅ None needed |
|
||||
| tsc-check | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
|
||||
| trigger-build-resolver | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
|
||||
| error-handling-reminder | Stop | ⚠️ Optional | ⚠️ Moderate |
|
||||
| stop-build-check-enhanced | Stop | ⚠️ Optional | ⚠️ Moderate |
|
||||
|
||||
**Start with the two essential hooks** - they enable skill auto-activation and work out of the box.
|
||||
|
||||
**👉 [Hook setup guide →](.claude/hooks/README.md)**
|
||||
|
||||
### 🤖 Agents (10)
|
||||
|
||||
**Standalone - just copy and use!**
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| code-architecture-reviewer | Review code for architectural consistency |
|
||||
| code-refactor-master | Plan and execute refactoring |
|
||||
| documentation-architect | Generate comprehensive documentation |
|
||||
| frontend-error-fixer | Debug frontend errors |
|
||||
| plan-reviewer | Review development plans |
|
||||
| refactor-planner | Create refactoring strategies |
|
||||
| web-research-specialist | Research technical issues online |
|
||||
| auth-route-tester | Test authenticated endpoints |
|
||||
| auth-route-debugger | Debug auth issues |
|
||||
| auto-error-resolver | Auto-fix TypeScript errors |
|
||||
|
||||
**👉 [How agents work →](.claude/agents/README.md)**
|
||||
|
||||
### 💬 Slash Commands (3)
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| /dev-docs | Create structured dev documentation |
|
||||
| /dev-docs-update | Update docs before context reset |
|
||||
| /route-research-for-testing | Research route patterns for testing |
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Hooks + skill-rules.json = Auto-Activation
|
||||
|
||||
**The system:**
|
||||
1. **skill-activation-prompt hook** runs on every user prompt
|
||||
2. Checks **skill-rules.json** for trigger patterns
|
||||
3. Suggests relevant skills automatically
|
||||
4. Skills load only when needed
|
||||
|
||||
**This solves the #1 problem** with Claude Code skills: they don't activate on their own.
|
||||
|
||||
### Progressive Disclosure (500-Line Rule)
|
||||
|
||||
**Problem:** Large skills hit context limits
|
||||
|
||||
**Solution:** Modular structure
|
||||
- Main SKILL.md <500 lines (overview + navigation)
|
||||
- Resource files <500 lines each (deep dives)
|
||||
- Claude loads incrementally as needed
|
||||
|
||||
**Example:** backend-dev-guidelines has 12 resource files covering routing, controllers, services, repositories, testing, etc.
|
||||
|
||||
### Dev Docs Pattern
|
||||
|
||||
**Problem:** Context resets lose project context
|
||||
|
||||
**Solution:** Three-file structure
|
||||
- `[task]-plan.md` - Strategic plan
|
||||
- `[task]-context.md` - Key decisions and files
|
||||
- `[task]-tasks.md` - Checklist format
|
||||
|
||||
**Works with:** `/dev-docs` slash command to generate these automatically
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important: What Won't Work As-Is
|
||||
|
||||
### settings.json
|
||||
The included `settings.json` is an **example only**:
|
||||
- Stop hooks reference specific monorepo structure
|
||||
- Service names (blog-api, etc.) are examples
|
||||
- MCP servers may not exist in your setup
|
||||
|
||||
**To use it:**
|
||||
1. Extract ONLY UserPromptSubmit and PostToolUse hooks
|
||||
2. Customize or skip Stop hooks
|
||||
3. Update MCP server list for your setup
|
||||
|
||||
### Blog Domain Examples
|
||||
Skills use generic blog examples (Post/Comment/User):
|
||||
- These are **teaching examples**, not requirements
|
||||
- Patterns work for any domain (e-commerce, SaaS, etc.)
|
||||
- Adapt the patterns to your business logic
|
||||
|
||||
### Hook Directory Structures
|
||||
Some hooks expect specific structures:
|
||||
- `tsc-check.sh` expects service directories
|
||||
- Customize based on YOUR project layout
|
||||
|
||||
---
|
||||
|
||||
## Integration Workflow
|
||||
|
||||
**Recommended approach:**
|
||||
|
||||
### Phase 1: Skill Activation (15 min)
|
||||
1. Copy skill-activation-prompt hook
|
||||
2. Copy post-tool-use-tracker hook
|
||||
3. Update settings.json
|
||||
4. Install hook dependencies
|
||||
|
||||
### Phase 2: Add First Skill (10 min)
|
||||
1. Pick ONE relevant skill
|
||||
2. Copy skill directory
|
||||
3. Create/update skill-rules.json
|
||||
4. Customize path patterns
|
||||
|
||||
### Phase 3: Test & Iterate (5 min)
|
||||
1. Edit a file - skill should activate
|
||||
2. Ask a question - skill should be suggested
|
||||
3. Add more skills as needed
|
||||
|
||||
### Phase 4: Optional Enhancements
|
||||
- Add agents you find useful
|
||||
- Add slash commands
|
||||
- Customize Stop hooks (advanced)
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### For Users
|
||||
**Issues with integration?**
|
||||
1. Check [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md)
|
||||
2. Ask Claude: "Why isn't [skill] activating?"
|
||||
3. Open an issue with your project structure
|
||||
|
||||
### For Claude Code
|
||||
When helping users integrate:
|
||||
1. **Read CLAUDE_INTEGRATION_GUIDE.md FIRST**
|
||||
2. Ask about their project structure
|
||||
3. Customize, don't blindly copy
|
||||
4. Verify after integration
|
||||
|
||||
---
|
||||
|
||||
## What This Solves
|
||||
|
||||
### Before This Infrastructure
|
||||
|
||||
❌ Skills don't activate automatically
|
||||
❌ Have to remember which skill to use
|
||||
❌ Large skills hit context limits
|
||||
❌ Context resets lose project knowledge
|
||||
❌ No consistency across development
|
||||
❌ Manual agent invocation every time
|
||||
|
||||
### After This Infrastructure
|
||||
|
||||
✅ Skills suggest themselves based on context
|
||||
✅ Hooks trigger skills at the right time
|
||||
✅ Modular skills stay under context limits
|
||||
✅ Dev docs preserve knowledge across resets
|
||||
✅ Consistent patterns via guardrails
|
||||
✅ Agents streamline complex tasks
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
**Found this useful?**
|
||||
|
||||
- ⭐ Star this repo
|
||||
- 🐛 Report issues or suggest improvements
|
||||
- 💬 Share your own skills/hooks/agents
|
||||
- 📝 Contribute examples from your domain
|
||||
|
||||
**Background:**
|
||||
This infrastructure was detailed in a post I made to Reddit ["Claude Code is a Beast – Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/). After hundreds of requests, this showcase was created to help the community implement these patterns.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Use freely in your projects, commercial or personal.
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- 📖 [Claude Integration Guide](CLAUDE_INTEGRATION_GUIDE.md) - For AI-assisted setup
|
||||
- 🎨 [Skills Documentation](.claude/skills/README.md)
|
||||
- 🪝 [Hooks Setup](.claude/hooks/README.md)
|
||||
- 🤖 [Agents Guide](.claude/agents/README.md)
|
||||
- 📝 [Dev Docs Pattern](dev/README.md)
|
||||
|
||||
**Start here:** Copy the two essential hooks, add one skill, and see the auto-activation magic happen.
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
# Dev Docs Pattern
|
||||
|
||||
A methodology for maintaining project context across Claude Code sessions and context resets.
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Context resets lose everything:**
|
||||
- Implementation decisions
|
||||
- Key files and their purposes
|
||||
- Task progress
|
||||
- Technical constraints
|
||||
- Why certain approaches were chosen
|
||||
|
||||
**After a reset, Claude has to rediscover everything.**
|
||||
|
||||
---
|
||||
|
||||
## The Solution: Persistent Dev Docs
|
||||
|
||||
A three-file structure that captures everything needed to resume work:
|
||||
|
||||
```
|
||||
dev/active/[task-name]/
|
||||
├── [task-name]-plan.md # Strategic plan
|
||||
├── [task-name]-context.md # Key decisions & files
|
||||
└── [task-name]-tasks.md # Checklist format
|
||||
```
|
||||
|
||||
**These files survive context resets** - Claude reads them to get back up to speed instantly.
|
||||
|
||||
---
|
||||
|
||||
## Three-File Structure
|
||||
|
||||
### 1. [task-name]-plan.md
|
||||
|
||||
**Purpose:** Strategic plan for the implementation
|
||||
|
||||
**Contains:**
|
||||
- Executive summary
|
||||
- Current state analysis
|
||||
- Proposed future state
|
||||
- Implementation phases
|
||||
- Detailed tasks with acceptance criteria
|
||||
- Risk assessment
|
||||
- Success metrics
|
||||
- Timeline estimates
|
||||
|
||||
**When to create:** At the start of a complex task
|
||||
|
||||
**When to update:** When scope changes or new phases discovered
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Implementation Plan
|
||||
|
||||
## Executive Summary
|
||||
What we're building and why
|
||||
|
||||
## Current State
|
||||
Where we are now
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Infrastructure (2 hours)
|
||||
- Task 1.1: Set up database schema
|
||||
- Acceptance: Schema compiles, relationships correct
|
||||
- Task 1.2: Create service structure
|
||||
- Acceptance: All directories created
|
||||
|
||||
### Phase 2: Core Functionality (3 hours)
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. [task-name]-context.md
|
||||
|
||||
**Purpose:** Key information for resuming work
|
||||
|
||||
**Contains:**
|
||||
- SESSION PROGRESS section (updated frequently!)
|
||||
- What's completed vs in-progress
|
||||
- Key files and their purposes
|
||||
- Important decisions made
|
||||
- Technical constraints discovered
|
||||
- Links to related files
|
||||
- Quick resume instructions
|
||||
|
||||
**When to create:** Start of task
|
||||
|
||||
**When to update:** **FREQUENTLY** - after major decisions, completions, or discoveries
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Context
|
||||
|
||||
## SESSION PROGRESS (2025-10-29)
|
||||
|
||||
### ✅ COMPLETED
|
||||
- Database schema created (User, Post, Comment models)
|
||||
- PostController implemented with BaseController pattern
|
||||
- Sentry integration working
|
||||
|
||||
### 🟡 IN PROGRESS
|
||||
- Creating PostService with business logic
|
||||
- File: src/services/postService.ts
|
||||
|
||||
### ⚠️ BLOCKERS
|
||||
- Need to decide on caching strategy
|
||||
|
||||
## Key Files
|
||||
|
||||
**src/controllers/PostController.ts**
|
||||
- Extends BaseController
|
||||
- Handles HTTP requests for posts
|
||||
- Delegates to PostService
|
||||
|
||||
**src/services/postService.ts** (IN PROGRESS)
|
||||
- Business logic for post operations
|
||||
- Next: Add caching
|
||||
|
||||
## Quick Resume
|
||||
To continue:
|
||||
1. Read this file
|
||||
2. Continue implementing PostService.createPost()
|
||||
3. See tasks file for remaining work
|
||||
```
|
||||
|
||||
**CRITICAL:** Update the SESSION PROGRESS section every time significant work is done!
|
||||
|
||||
---
|
||||
|
||||
### 3. [task-name]-tasks.md
|
||||
|
||||
**Purpose:** Checklist for tracking progress
|
||||
|
||||
**Contains:**
|
||||
- Phases broken down by logical sections
|
||||
- Tasks in checkbox format
|
||||
- Status indicators (✅/🟡/⏳)
|
||||
- Acceptance criteria
|
||||
- Quick resume section
|
||||
|
||||
**When to create:** Start of task
|
||||
|
||||
**When to update:** After completing each task or discovering new tasks
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Task Checklist
|
||||
|
||||
## Phase 1: Setup ✅ COMPLETE
|
||||
- [x] Create database schema
|
||||
- [x] Set up controllers
|
||||
- [x] Configure Sentry
|
||||
|
||||
## Phase 2: Implementation 🟡 IN PROGRESS
|
||||
- [x] Create PostController
|
||||
- [ ] Create PostService (IN PROGRESS)
|
||||
- [ ] Create PostRepository
|
||||
- [ ] Add validation with Zod
|
||||
|
||||
## Phase 3: Testing ⏳ NOT STARTED
|
||||
- [ ] Unit tests for service
|
||||
- [ ] Integration tests
|
||||
- [ ] Manual API testing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Dev Docs
|
||||
|
||||
**Use for:**
|
||||
- ✅ Complex multi-day tasks
|
||||
- ✅ Features with many moving parts
|
||||
- ✅ Tasks likely to span multiple sessions
|
||||
- ✅ Work that needs careful planning
|
||||
- ✅ Refactoring large systems
|
||||
|
||||
**Skip for:**
|
||||
- ❌ Simple bug fixes
|
||||
- ❌ Single-file changes
|
||||
- ❌ Quick updates
|
||||
- ❌ Trivial modifications
|
||||
|
||||
**Rule of thumb:** If it takes more than 2 hours or spans multiple sessions, use dev docs.
|
||||
|
||||
---
|
||||
|
||||
## Workflow with Dev Docs
|
||||
|
||||
### Starting a New Task
|
||||
|
||||
1. **Use /dev-docs slash command:**
|
||||
```
|
||||
/dev-docs refactor authentication system
|
||||
```
|
||||
|
||||
2. **Claude creates the three files:**
|
||||
- Analyzes requirements
|
||||
- Examines codebase
|
||||
- Creates comprehensive plan
|
||||
- Generates context and tasks files
|
||||
|
||||
3. **Review and adjust:**
|
||||
- Check if plan makes sense
|
||||
- Add any missing considerations
|
||||
- Adjust timeline estimates
|
||||
|
||||
### During Implementation
|
||||
|
||||
1. **Refer to plan** for overall strategy
|
||||
2. **Update context.md** frequently:
|
||||
- Mark completed work
|
||||
- Note decisions made
|
||||
- Add blockers
|
||||
3. **Check off tasks** in tasks.md as you complete them
|
||||
|
||||
### After Context Reset
|
||||
|
||||
1. **Claude reads all three files**
|
||||
2. **Understands complete state** in seconds
|
||||
3. **Resumes exactly where you left off**
|
||||
|
||||
No need to explain what you were doing - it's all documented!
|
||||
|
||||
---
|
||||
|
||||
## Integration with Slash Commands
|
||||
|
||||
### /dev-docs
|
||||
**Creates:** New dev docs for a task
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/dev-docs implement real-time notifications
|
||||
```
|
||||
|
||||
**Generates:**
|
||||
- `dev/active/implement-real-time-notifications/`
|
||||
- implement-real-time-notifications-plan.md
|
||||
- implement-real-time-notifications-context.md
|
||||
- implement-real-time-notifications-tasks.md
|
||||
|
||||
### /dev-docs-update
|
||||
**Updates:** Existing dev docs before context reset
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/dev-docs-update
|
||||
```
|
||||
|
||||
**Updates:**
|
||||
- Marks completed tasks
|
||||
- Adds new tasks discovered
|
||||
- Updates context with session progress
|
||||
- Captures current state
|
||||
|
||||
**Use when:** Approaching context limits or ending session
|
||||
|
||||
---
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
dev/
|
||||
├── README.md # This file
|
||||
├── active/ # Current work
|
||||
│ ├── task-1/
|
||||
│ │ ├── task-1-plan.md
|
||||
│ │ ├── task-1-context.md
|
||||
│ │ └── task-1-tasks.md
|
||||
│ └── task-2/
|
||||
│ └── ...
|
||||
└── archive/ # Completed work (optional)
|
||||
└── old-task/
|
||||
└── ...
|
||||
```
|
||||
|
||||
**active/**: Work in progress
|
||||
**archive/**: Completed tasks (for reference)
|
||||
|
||||
---
|
||||
|
||||
## Example: Real Usage
|
||||
|
||||
See **dev/active/public-infrastructure-repo/** in this repository for a real example:
|
||||
- **plan.md** - 700+ line strategic plan for creating this showcase
|
||||
- **context.md** - Tracks what's completed, decisions made, what's next
|
||||
- **tasks.md** - Checklist of all phases and tasks
|
||||
|
||||
This is the actual dev docs used to build this showcase!
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Update Context Frequently
|
||||
|
||||
**Bad:** Update only at end of session
|
||||
**Good:** Update after each major milestone
|
||||
|
||||
**SESSION PROGRESS section should always reflect reality:**
|
||||
```markdown
|
||||
## SESSION PROGRESS (YYYY-MM-DD)
|
||||
|
||||
### ✅ COMPLETED (list everything done)
|
||||
### 🟡 IN PROGRESS (what you're working on RIGHT NOW)
|
||||
### ⚠️ BLOCKERS (what's preventing progress)
|
||||
```
|
||||
|
||||
### Make Tasks Actionable
|
||||
|
||||
**Bad:** "Fix the authentication"
|
||||
**Good:** "Implement JWT token validation in AuthMiddleware.ts (Acceptance: Tokens validated, errors to Sentry)"
|
||||
|
||||
**Include:**
|
||||
- Specific file names
|
||||
- Clear acceptance criteria
|
||||
- Dependencies on other tasks
|
||||
|
||||
### Keep Plan Current
|
||||
|
||||
If scope changes:
|
||||
- Update the plan
|
||||
- Add new phases
|
||||
- Adjust timeline estimates
|
||||
- Note why scope changed
|
||||
|
||||
---
|
||||
|
||||
## For Claude Code
|
||||
|
||||
**When user asks to create dev docs:**
|
||||
|
||||
1. **Use the /dev-docs slash command** if available
|
||||
2. **Or create manually:**
|
||||
- Ask about the task scope
|
||||
- Analyze relevant codebase files
|
||||
- Create comprehensive plan
|
||||
- Generate context and tasks
|
||||
|
||||
3. **Structure the plan with:**
|
||||
- Clear phases
|
||||
- Actionable tasks
|
||||
- Acceptance criteria
|
||||
- Risk assessment
|
||||
|
||||
4. **Make context file resumable:**
|
||||
- SESSION PROGRESS at top
|
||||
- Quick resume instructions
|
||||
- Key files list with explanations
|
||||
|
||||
**When resuming from dev docs:**
|
||||
|
||||
1. **Read all three files** (plan, context, tasks)
|
||||
2. **Start with context.md** - has current state
|
||||
3. **Check tasks.md** - see what's done and what's next
|
||||
4. **Refer to plan.md** - understand overall strategy
|
||||
|
||||
**Update frequently:**
|
||||
- Mark tasks complete immediately
|
||||
- Update SESSION PROGRESS after significant work
|
||||
- Add new tasks as discovered
|
||||
|
||||
---
|
||||
|
||||
## Creating Dev Docs Manually
|
||||
|
||||
If you don't have the /dev-docs command:
|
||||
|
||||
**1. Create directory:**
|
||||
```bash
|
||||
mkdir -p dev/active/your-task-name
|
||||
```
|
||||
|
||||
**2. Create plan.md:**
|
||||
- Executive summary
|
||||
- Implementation phases
|
||||
- Detailed tasks
|
||||
- Timeline estimates
|
||||
|
||||
**3. Create context.md:**
|
||||
- SESSION PROGRESS section
|
||||
- Key files
|
||||
- Important decisions
|
||||
- Quick resume instructions
|
||||
|
||||
**4. Create tasks.md:**
|
||||
- Phases with checkboxes
|
||||
- [ ] Task format
|
||||
- Acceptance criteria
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
**Before dev docs:**
|
||||
- Context reset = start over
|
||||
- Forget why decisions were made
|
||||
- Lose track of progress
|
||||
- Repeat work
|
||||
|
||||
**After dev docs:**
|
||||
- Context reset = read 3 files, resume instantly
|
||||
- Decisions documented
|
||||
- Progress tracked
|
||||
- No repeated work
|
||||
|
||||
**Time saved:** Hours per context reset
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Try the pattern** on your next complex task
|
||||
2. **Use /dev-docs** slash command (if available)
|
||||
3. **Update frequently** - especially context.md
|
||||
4. **See it in action** - Browse dev/active/public-infrastructure-repo/
|
||||
|
||||
**Questions?** See [CLAUDE_INTEGRATION_GUIDE.md](../CLAUDE_INTEGRATION_GUIDE.md)
|
||||
Loading…
Reference in New Issue