From bf0a30e0aecc984030c82faaa14a12dd456ad0b8 Mon Sep 17 00:00:00 2001 From: dzq Date: Wed, 12 Nov 2025 09:34:03 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0Claude=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E5=9F=BA=E7=A1=80=E8=AE=BE=E6=96=BD=E5=B1=95=E7=A4=BA?= =?UTF-8?q?=E5=BA=93=E5=88=9D=E5=A7=8B=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs: 新增项目文档和开发指南 chore: 添加.gitignore和LICENSE文件 --- .../.gitignore | 51 + .../CLAUDE_INTEGRATION_GUIDE.md | 883 ++++++++++++++++++ .../LICENSE | 21 + .../README.md | 360 +++++++ .../dev/README.md | 424 +++++++++ 5 files changed, 1739 insertions(+) create mode 100644 source/documents/claude-code-infrastructure-showcase/.gitignore create mode 100644 source/documents/claude-code-infrastructure-showcase/CLAUDE_INTEGRATION_GUIDE.md create mode 100644 source/documents/claude-code-infrastructure-showcase/LICENSE create mode 100644 source/documents/claude-code-infrastructure-showcase/README.md create mode 100644 source/documents/claude-code-infrastructure-showcase/dev/README.md diff --git a/source/documents/claude-code-infrastructure-showcase/.gitignore b/source/documents/claude-code-infrastructure-showcase/.gitignore new file mode 100644 index 0000000..dbb0d1f --- /dev/null +++ b/source/documents/claude-code-infrastructure-showcase/.gitignore @@ -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 diff --git a/source/documents/claude-code-infrastructure-showcase/CLAUDE_INTEGRATION_GUIDE.md b/source/documents/claude-code-infrastructure-showcase/CLAUDE_INTEGRATION_GUIDE.md new file mode 100644 index 0000000..1a9f43f --- /dev/null +++ b/source/documents/claude-code-infrastructure-showcase/CLAUDE_INTEGRATION_GUIDE.md @@ -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. diff --git a/source/documents/claude-code-infrastructure-showcase/LICENSE b/source/documents/claude-code-infrastructure-showcase/LICENSE new file mode 100644 index 0000000..a1875f4 --- /dev/null +++ b/source/documents/claude-code-infrastructure-showcase/LICENSE @@ -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. diff --git a/source/documents/claude-code-infrastructure-showcase/README.md b/source/documents/claude-code-infrastructure-showcase/README.md new file mode 100644 index 0000000..1df332b --- /dev/null +++ b/source/documents/claude-code-infrastructure-showcase/README.md @@ -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. diff --git a/source/documents/claude-code-infrastructure-showcase/dev/README.md b/source/documents/claude-code-infrastructure-showcase/dev/README.md new file mode 100644 index 0000000..bf93a04 --- /dev/null +++ b/source/documents/claude-code-infrastructure-showcase/dev/README.md @@ -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)