aiblueprint-cli 1.4.11 → 1.4.13

package/claude-code-config/skills/claude-memory/SKILL.md

@@ -0,0 +1,689 @@
+---
+name: claude-memory
+description: Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Comprehensive guidance on file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness.
+argument-hint: [task description]
+---
+
+<objective>
+Master the creation of effective Claude Code memory systems using either CLAUDE.md files or the modular `.claude/rules/` directory. This skill covers file hierarchy, content structure, path-scoped rules, formatting, emphasis techniques, and common anti-patterns to avoid.
+
+Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Claude Code's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations.
+
+**Two approaches available:**
+
+- **CLAUDE.md** - Single file, simpler, best for small projects
+- **.claude/rules/** - Modular files with optional path-scoping, best for large projects
+  </objective>
+
+<quick_start>
+<bootstrap_new_project>
+Run `/init` in Claude Code to auto-generate a CLAUDE.md with project structure.
+
+Or create manually at project root:
+
+```markdown
+# Project Name
+
+## Tech Stack
+
+- [Primary language/framework]
+- [Key libraries]
+
+## Commands
+
+- `npm run dev` - Start development
+- `npm test` - Run tests
+- `npm run build` - Build for production
+
+## Code Conventions
+
+- [2-3 critical conventions]
+
+## Important Context
+
+- [1-2 architectural decisions worth knowing]
+```
+
+</bootstrap_new_project>
+
+<quick_add_memory>
+Press `#` during a Claude Code session to quickly add new memory items without editing the file directly.
+</quick_add_memory>
+
+<edit_memory>
+Use `/memory` command to open CLAUDE.md in your system editor.
+</edit_memory>
+</quick_start>
+
+<file_hierarchy>
+Claude Code loads CLAUDE.md files in a specific order. Higher priority files are loaded first and take precedence.
+
+<loading_order>
+| Priority | Location | Purpose | Scope |
+|----------|----------|---------|-------|
+| 1 (Highest) | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | Enterprise policy (managed by IT) | All org users |
+| 2 | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project memory (git-tracked) | Team via git |
+| 2 | `./.claude/rules/*.md` | Modular rules (git-tracked) | Team via git |
+| 3 | `~/.claude/CLAUDE.md` | User preferences (global) | All your projects |
+| 3 | `~/.claude/rules/*.md` | Personal modular rules (global) | All your projects |
+| 4 (Lowest) | `./CLAUDE.local.md` | Personal project prefs (auto-gitignored) | Just you |
+</loading_order>
+
+<recursive_loading>
+Claude recurses UP from current directory to root, loading all CLAUDE.md files found.
+
+Running Claude in `foo/bar/` loads:
+
+1. `foo/bar/CLAUDE.md`
+2. `foo/CLAUDE.md`
+3. Root-level files
+
+Claude also discovers CLAUDE.md in SUBTREES when reading files in those directories.
+</recursive_loading>
+
+<monorepo_strategy>
+For monorepos, use layered approach:
+
+```
+root/
+├── CLAUDE.md              # Universal: tech stack, git workflow
+├── apps/
+│   ├── web/CLAUDE.md      # Frontend-specific patterns
+│   └── api/CLAUDE.md      # Backend-specific patterns
+└── packages/
+    └── shared/CLAUDE.md   # Shared library conventions
+```
+
+Root file defines WHEN to use patterns; subtree files define HOW.
+</monorepo_strategy>
+</file_hierarchy>
+
+<rules_directory>
+The `.claude/rules/` directory provides a **modular alternative** to monolithic CLAUDE.md files. Instead of one large file, you organize instructions into multiple focused markdown files.
+
+<when_to_use_rules>
+**Use `.claude/rules/` when:**
+
+- Project has many distinct concerns (testing, security, API, frontend)
+- Different rules apply to different file types
+- Team members maintain different areas
+- You want to update one concern without touching others
+
+**Use CLAUDE.md when:**
+
+- Project is small/simple
+- All rules are universal
+- You prefer a single source of truth
+  </when_to_use_rules>
+
+<rules_structure>
+
+```
+.claude/rules/
+├── code-style.md      # Formatting and conventions
+├── testing.md         # Test requirements
+├── security.md        # Security checklist
+├── frontend/
+│   ├── react.md       # React-specific patterns
+│   └── styles.md      # CSS conventions
+└── backend/
+    ├── api.md         # API development rules
+    └── database.md    # Database conventions
+```
+
+**Key points:**
+
+- All `.md` files are discovered recursively
+- No imports or configuration needed
+- Same priority as CLAUDE.md
+- Supports symlinks for sharing rules across projects
+  </rules_structure>
+
+<path_scoped_rules>
+Rules can be scoped to specific files using YAML frontmatter:
+
+```yaml
+---
+paths: src/api/**/*.ts
+---
+# API Development Rules
+
+- All API endpoints must include input validation
+- Use the standard error response format
+```
+
+**Path patterns supported:**
+
+| Pattern                | Matches                                    |
+| ---------------------- | ------------------------------------------ |
+| `**/*.ts`              | All TypeScript files in any directory      |
+| `src/**/*`             | All files under `src/` directory           |
+| `src/components/*.tsx` | React components in specific directory     |
+| `src/**/*.{ts,tsx}`    | TypeScript and TSX files (brace expansion) |
+| `{src,lib}/**/*.ts`    | Files in multiple directories              |
+
+**Rules without `paths` frontmatter** load unconditionally for all files.
+</path_scoped_rules>
+
+<user_level_rules>
+Create personal rules that apply to all your projects:
+
+```
+~/.claude/rules/
+├── preferences.md    # Your coding preferences
+├── workflows.md      # Your preferred workflows
+└── git.md            # Your git conventions
+```
+
+User-level rules load before project rules, giving project rules higher priority for overrides.
+</user_level_rules>
+
+<symlinks_support>
+Share common rules across multiple projects using symlinks:
+
+```bash
+# Symlink a shared rules directory
+ln -s ~/shared-claude-rules .claude/rules/shared
+
+# Symlink individual rule files
+ln -s ~/company-standards/security.md .claude/rules/security.md
+```
+
+Circular symlinks are detected and handled gracefully.
+</symlinks_support>
+</rules_directory>
+
+<content_framework>
+Structure your CLAUDE.md using the WHAT-WHY-HOW framework:
+
+**WHAT** - Project Context: Tech stack, directory structure, architecture
+**WHY** - Purpose: Architectural decisions, why patterns exist
+**HOW** - Workflow: Commands, testing, git workflow, verification steps
+
+```markdown
+## Tech Stack
+
+- Next.js 15 with App Router
+- PostgreSQL via Prisma ORM
+
+## Architecture Decisions
+
+- Server Components for data fetching
+- All forms use TanStack Form
+
+## Commands
+
+- `pnpm dev` - Start dev server
+- `pnpm test:ci` - Run tests
+- `pnpm build` - Production build
+
+## Git Workflow
+
+- Branch: `feature/name` or `fix/name`
+- Run tests before committing
+```
+
+See [references/section-templates.md](references/section-templates.md) for complete templates.
+</content_framework>
+
+<emphasis_techniques>
+Claude follows emphasized instructions more reliably. Use these techniques strategically for critical rules.
+
+<keyword_hierarchy>
+Use emphasis keywords in order of severity:
+
+| Keyword       | Use For               | Example                                      |
+| ------------- | --------------------- | -------------------------------------------- |
+| **CRITICAL**  | Non-negotiable rules  | `**CRITICAL**: Never commit secrets`         |
+| **NEVER**     | Absolute prohibitions | `NEVER: Push directly to main`               |
+| **ALWAYS**    | Mandatory behaviors   | `ALWAYS: Run tests before pushing`           |
+| **IMPORTANT** | Significant guidance  | `IMPORTANT: Keep components under 300 lines` |
+| **YOU MUST**  | Explicit requirements | `YOU MUST: Use TanStack Form for forms`      |
+
+</keyword_hierarchy>
+
+<formatting_patterns>
+**Bold + CRITICAL keyword:**
+
+```markdown
+**CRITICAL**: Always run tests before pushing code
+```
+
+**Capitalized emphasis:**
+
+```markdown
+IMPORTANT: Do not commit environment variables
+YOU MUST: Follow the git workflow outlined below
+NEVER: Include API keys in code
+ALWAYS: Use TypeScript strict mode
+```
+
+**Strikethrough for forbidden options:**
+
+```markdown
+- `pnpm test:ci` - Run tests (use this)
+- ~~`pnpm test`~~ - NEVER use (interactive mode)
+```
+
+**Visual markers (use sparingly):**
+
+```markdown
+⚠️ WARNING: This affects production data
+🔒 SECURITY: Never commit secrets to git
+```
+
+</formatting_patterns>
+
+<placement_strategy>
+Order matters. Claude pays more attention to:
+
+1. **First items** in each section (put critical rules first)
+2. **Repeated items** across sections (repeat critical rules in context)
+3. **Emphasized items** with CRITICAL/NEVER/ALWAYS keywords
+
+Structure your file with critical rules first:
+
+```markdown
+## Code Conventions
+
+### Critical Rules
+
+- **NEVER** commit .env files
+- **ALWAYS** run tests before pushing
+- **CRITICAL**: Use TanStack Form for ALL forms
+
+### General Guidelines
+
+- Prefer Server Components
+- Keep components under 300 lines
+```
+
+</placement_strategy>
+
+<repetition_for_emphasis>
+For extremely important rules, repeat in multiple relevant contexts:
+
+```markdown
+## Forms
+
+**CRITICAL**: Use TanStack Form for ALL forms
+
+## Before Editing
+
+- **CRITICAL**: Use TanStack Form for forms
+
+## Code Review Checklist
+
+- [ ] Forms use TanStack Form (**CRITICAL**)
+```
+
+</repetition_for_emphasis>
+</emphasis_techniques>
+
+<writing_effective_instructions>
+<golden_rule>
+Show your CLAUDE.md to someone with minimal project context. If they're confused, Claude will be too.
+</golden_rule>
+
+<be_specific>
+Vague instructions cause inconsistent behavior:
+
+```markdown
+❌ VAGUE:
+
+- Format code properly
+- Write good tests
+- Follow best practices
+
+✅ SPECIFIC:
+
+- Run `pnpm lint` before committing (Prettier configured)
+- Write tests in `__tests__/` using Vitest
+- Use TanStack Form for all forms (see `src/features/form/`)
+```
+
+</be_specific>
+
+<show_dont_tell>
+When format matters, show examples:
+
+```markdown
+❌ TELLING:
+Use conventional commits with type and description.
+
+✅ SHOWING:
+
+## Commit Format
+```
+
+feat(auth): implement JWT authentication
+
+Add login endpoint and token validation
+
+```
+Types: feat, fix, refactor, docs, test, chore
+```
+
+</show_dont_tell>
+
+<eliminate_ambiguity>
+Replace vague phrases with clear directives:
+
+| Ambiguous            | Clear Alternative                   |
+| -------------------- | ----------------------------------- |
+| "Try to..."          | "Always..." or "Never..."           |
+| "Should probably..." | "Must..." or "May optionally..."    |
+| "Generally..."       | "Always... except when [condition]" |
+| "Consider..."        | "If [condition], then [action]"     |
+
+</eliminate_ambiguity>
+
+<define_edge_cases>
+Anticipate questions and answer them:
+
+```markdown
+❌ INCOMPLETE:
+Run tests before pushing.
+
+✅ COMPLETE:
+
+## Testing
+
+- Run `pnpm test:ci` before pushing
+- If tests fail, fix before committing
+- New features require tests in `__tests__/`
+- Minimum 80% coverage for new code
+```
+
+</define_edge_cases>
+
+<provide_decision_criteria>
+When Claude must make choices, give criteria:
+
+```markdown
+## Component Choice
+
+**Use Server Component when:**
+
+- Data fetching only
+- No user interaction needed
+
+**Use Client Component when:**
+
+- User interaction required
+- Browser APIs needed (localStorage, window)
+```
+
+</provide_decision_criteria>
+
+<separate_obligation_levels>
+Clearly distinguish requirements from suggestions:
+
+```markdown
+## API Development
+
+### Must Have
+
+- Input validation with Zod
+- Error handling for all endpoints
+
+### Nice to Have
+
+- Pagination for list endpoints
+- Caching headers
+
+### Must Not
+
+- Expose internal errors to clients
+- Log sensitive data
+```
+
+</separate_obligation_levels>
+</writing_effective_instructions>
+
+<size_constraints>
+<limits>
+
+- **Ideal**: 100-200 lines maximum
+- **Practical max**: 300 lines before splitting
+- **Universal items**: Under 60 lines
+
+**Why these limits matter:**
+
+- Claude reliably follows ~150-200 total instructions
+- Claude Code's system prompt uses ~50 instructions
+- Leaves ~100-150 slots for YOUR instructions
+- Irrelevant content degrades instruction-following
+  </limits>
+
+<scaling_strategy>
+When exceeding limits:
+
+1. Move task-specific details to separate files
+2. Link from CLAUDE.md with descriptions
+3. Use progressive disclosure pattern
+
+```markdown
+## Detailed Guides
+
+- **API Routes**: See [docs/api-patterns.md](docs/api-patterns.md)
+- **Testing**: See [docs/testing-guide.md](docs/testing-guide.md)
+- **Deployment**: See [docs/deployment.md](docs/deployment.md)
+```
+
+</scaling_strategy>
+</size_constraints>
+
+<imports_feature>
+CLAUDE.md supports importing other markdown files:
+
+```markdown
+## External References
+
+@docs/coding-standards.md
+@~/.claude/my-global-preferences.md
+@./team-conventions.md
+```
+
+<import_rules>
+
+- Supports relative and absolute paths
+- Home directory expansion with `~`
+- Recursive imports up to 5 levels deep
+- NOT evaluated inside code blocks or backticks
+  </import_rules>
+  </imports_feature>
+
+<anti_patterns>
+<never_include>
+**Code Style Rules** - Use linters instead (LLMs are expensive, linters are free)
+
+**Secrets** - NEVER include API keys, database URLs, tokens, credentials
+
+**Too Much Content** - Link to docs instead of embedding 500+ lines
+
+**Extensive Code** - Reference files instead (code examples become outdated)
+
+**Vague Instructions** - Be specific (see `<writing_effective_instructions>`)
+</never_include>
+
+<examples_what_to_avoid>
+
+```markdown
+❌ BAD:
+
+- Use 2-space indentation (use Prettier instead)
+- DATABASE_URL=postgresql://... (never include secrets)
+- [500 lines of API docs] (link to external file)
+- Format code properly (too vague)
+
+✅ GOOD:
+
+- ESLint/Prettier configured (see .eslintrc)
+- Credentials in `.env` (never committed)
+- API guide: See [docs/api.md](docs/api.md)
+- Run `pnpm lint` before committing
+```
+
+</examples_what_to_avoid>
+</anti_patterns>
+
+<examples>
+For complete examples, see reference files:
+
+- **Minimal example**: [references/section-templates.md](references/section-templates.md) (templates section)
+- **Comprehensive SaaS**: [references/comprehensive-example.md](references/comprehensive-example.md)
+- **Project-specific**: [references/project-patterns.md](references/project-patterns.md) (Next.js, Express, Python, Monorepo)
+  </examples>
+
+<workflow>
+<decision_point>
+**ALWAYS ASK FIRST: Storage Strategy**
+
+Before creating or updating memory files, ask the user:
+
+> Do you want to use a single CLAUDE.md file or split into separate `.claude/rules/` files?
+>
+> **Option 1: Single CLAUDE.md** - All instructions in one file (simpler, best for small projects)
+> **Option 2: Modular .claude/rules/** - Split by concern with optional path-scoping (better for large projects)
+
+Use AskUserQuestion to present these options before proceeding.
+
+**Decision guide:**
+
+- **Choose CLAUDE.md** if: < 100 lines of instructions, simple project, universal rules
+- **Choose .claude/rules/** if: 100+ lines, multiple file types with different rules, team maintains different areas
+  </decision_point>
+
+<creating_new>
+**Creating New Memory (CLAUDE.md approach)**
+
+1. Start with `/init` or minimal template
+2. Add tech stack and commands first
+3. Add conventions as you encounter friction
+4. Test with real tasks
+5. Iterate based on Claude's behavior
+   </creating_new>
+
+<creating_rules>
+**Creating New Memory (.claude/rules/ approach)**
+
+1. Create `.claude/rules/` directory
+2. Start with one file per major concern:
+   - `general.md` - Universal project rules
+   - `testing.md` - Testing conventions
+   - `code-style.md` - Code conventions
+3. Add path-scoped rules as needed:
+   ```yaml
+   ---
+   paths: src/api/**/*.ts
+   ---
+   # API rules here
+   ```
+4. Test with real tasks in different file contexts
+5. Split or merge files based on usage patterns
+   </creating_rules>
+
+<maintaining>
+**Maintaining Memory Files**
+
+1. Review quarterly (or when project changes significantly)
+2. Remove outdated instructions
+3. Add patterns that required repeated explanation
+4. Keep CLAUDE.md under 200 lines (or split to .claude/rules/)
+5. Use `#` for quick additions during work
+   </maintaining>
+
+<migrating_to_rules>
+**Migrating from CLAUDE.md to .claude/rules/**
+
+When CLAUDE.md exceeds 200 lines:
+
+1. Identify distinct sections (testing, API, frontend, etc.)
+2. Create `.claude/rules/` directory
+3. Move each section to its own file
+4. Add `paths` frontmatter where rules are file-type specific
+5. Keep only universal essentials in CLAUDE.md (or delete it)
+6. Test to ensure rules load correctly
+   </migrating_to_rules>
+
+<troubleshooting>
+**Common Issues**
+
+| Problem                     | Solution                                         |
+| --------------------------- | ------------------------------------------------ |
+| Claude ignores instructions | Reduce file size, add emphasis (CRITICAL, NEVER) |
+| Context overflow            | Use `/clear`, split into .claude/rules/ files    |
+| Outdated information        | Review quarterly, remove stale content           |
+| Instructions conflict       | Consolidate, use hierarchy (root vs subtree)     |
+| Rules not loading           | Check file is `.md`, in correct directory        |
+| Path rules not applying     | Verify glob pattern matches target files         |
+
+</troubleshooting>
+</workflow>
+
+<advanced_features>
+<local_overrides>
+Use `CLAUDE.local.md` for personal preferences (auto-gitignored):
+
+- Personal shortcuts and aliases
+- Editor-specific settings
+- Local testing commands
+  </local_overrides>
+
+<settings_integration>
+CLAUDE.md works alongside `settings.json`:
+
+- `settings.json`: Permissions, allowed tools, environment variables
+- `CLAUDE.md`: Context, conventions, workflow instructions
+  </settings_integration>
+
+<progressive_disclosure>
+For complex projects, link to detailed docs. Claude only loads when relevant:
+
+```markdown
+## References
+
+- **Database**: See [docs/database.md](docs/database.md)
+- **API**: See [docs/api.md](docs/api.md)
+```
+
+</progressive_disclosure>
+</advanced_features>
+
+<success_criteria>
+A well-crafted Claude memory system:
+
+**For CLAUDE.md approach:**
+
+- Loads in under 200 lines
+- Contains only project-specific context (not general knowledge)
+- Uses emphasis for critical rules (CRITICAL, NEVER, ALWAYS)
+- Avoids code style rules (use linters)
+- Contains NO secrets or credentials
+- Provides clear commands for common tasks
+- Follows WHAT-WHY-HOW structure
+
+**For .claude/rules/ approach:**
+
+- Each file focused on one concern (testing, API, security, etc.)
+- Path-scoped rules use accurate glob patterns
+- No duplicate rules across files
+- Files organized in logical subdirectories
+- Symlinks used for shared rules across projects
+
+**Both approaches:**
+
+- Gets updated as project evolves
+- Improves Claude's first-try accuracy on tasks
+- User was asked which approach they prefer before implementation
+  </success_criteria>
+
+<reference_guides>
+For deeper topics:
+
+- **Prompting techniques**: [references/prompting-techniques.md](references/prompting-techniques.md) - Master guide for writing effective instructions, emphasis strategies, clarity techniques
+- **Comprehensive example**: [references/comprehensive-example.md](references/comprehensive-example.md) - Full production SaaS CLAUDE.md
+- **Section templates**: [references/section-templates.md](references/section-templates.md) - Copy-paste templates for each section
+- **Common patterns by project type**: [references/project-patterns.md](references/project-patterns.md) - Next.js, Express, Python, Monorepo patterns
+  </reference_guides>