Initial commit

skills/claude-md-reflect/references/anthropic-best-practices.md

@@ -0,0 +1,87 @@
+# CLAUDE.md Best Practices
+
+Reference: Official Anthropic documentation
+
+- https://code.claude.com/docs/en/memory
+- https://www.anthropic.com/engineering/claude-code-best-practices
+
+
+## What to Include
+
+- Common bash commands with descriptions
+- Core files and utility functions
+- Code style guidelines
+- Testing instructions and workflows
+- Repository etiquette (branch naming, merge vs. rebase)
+- Developer environment setup (tool versions, compiler requirements)
+- Project-specific quirks or unexpected behaviors
+- Information to remember across sessions
+
+## Format and Structure
+
+- Keep concise and human-readable
+- Use simple lists with brief explanations
+- Use bullet points, not lengthy prose
+- Use descriptive markdown headings to organize related items
+
+Example:
+```
+# Bash commands
+- npm run build: Build the project
+- npm run test: Run test suite
+
+# Code style
+- Use ES modules syntax
+- Destructure imports when possible
+```
+
+## File Placement
+
+- **Repository root**: `./CLAUDE.md` or `./.claude/CLAUDE.md` (checked into git for team sharing)
+- **Subdirectories**: In monorepos for project-specific guidance
+- **Home folder**: `~/.claude/CLAUDE.md` for personal preferences across all sessions
+- **Local variants**: `./CLAUDE.local.md` (.gitignored) for machine-specific configuration
+
+## CLAUDE.md Hierarchy
+
+Files are loaded recursively from current directory up to root, in this order:
+1. Enterprise policy (system-wide)
+2. Project memory (repository root)
+3. User memory (home folder)
+4. Project memory local (current project only)
+
+Files higher in hierarchy take precedence.
+
+## Imports
+
+CLAUDE.md files can import additional files using `@path/to/import` syntax:
+
+```
+See @README for project overview and @package.json for available npm commands.
+
+# Additional Instructions
+- git workflow @docs/git-instructions.md
+- @~/.claude/my-project-instructions.md
+```
+
+- Both relative and absolute paths allowed
+- Imports not evaluated inside code spans or blocks
+- Max depth: 5 hops
+
+## Best Practices
+
+- **Be specific**: "Use 2-space indentation" not "Format code properly"
+- **Use structure**: Format as bullet points, group under descriptive headings
+- **Iterate continuously**: Test effectiveness rather than adding extensively
+- **Add emphasis**: Use "IMPORTANT" or "YOU MUST" for critical instructions
+- **Review periodically**: Update as project evolves
+- **Include in commits**: Share accumulated guidance with teammates
+
+## What to Avoid
+
+- Bloated files without validating impact on performance
+- Redundancy with existing documentation
+- Long narrative paragraphs
+- Commentary or nice-to-have information
+- Hyperbolic or subjective language
+- Vague instructions

skills/claude-md-reflect/references/anti-patterns.md

@@ -0,0 +1,182 @@
+# CLAUDE.md Anti-Patterns
+
+Common mistakes to avoid when writing or improving CLAUDE.md files. You should AVOID the following:
+
+## Vague or Subjective Instructions
+
+**Bad:**
+- Write proper code
+- Use best practices
+- Make it simple
+- Write robust error handling
+- Create clean functions
+
+**Why:** These are subjective and provide no actionable guidance.
+
+**Good:**
+- Use 2-space indentation
+- Prefix test files with `test_`
+- Return errors instead of panicking
+- Functions should not exceed 50 lines
+
+## Hyperbolic or Fluff Language
+
+**Bad:**
+- The API client plays a crucial role in our architecture
+- It's very important to follow these guidelines
+- Make sure to write excellent documentation
+- Always use proper naming conventions
+
+**Why:** Words like "crucial", "very important", "excellent", "proper" add noise without meaning.
+
+**Good:**
+- Use the API client in `pkg/client` for all external requests
+- Document all exported functions
+- Use snake_case for variable names
+
+## Long Narrative Paragraphs
+
+**Bad:**
+```
+When you're working on this project, you should be aware that we have a
+specific way of handling errors. In the past, we used to just return nil
+and log errors, but we've since moved to a better approach where we return
+the actual error values so that callers can handle them appropriately.
+```
+
+**Good:**
+```
+# Error handling
+- Return errors to callers, don't just log them
+- Use errors.Join for multiple errors
+```
+
+## Redundant Information
+
+**Bad:**
+```
+# Build commands
+- npm run build: This command builds the project
+- npm run test: This command runs the tests
+- npm run lint: This command runs the linter
+
+# Building
+To build the project, run `npm run build`
+```
+
+**Why:** Information appears multiple times.
+
+**Good:**
+```
+# Commands
+- npm run build: Build the project
+- npm run test: Run test suite
+- npm run lint: Check code style
+```
+
+## Outdated Instructions
+
+**Bad:**
+```
+# Database
+- Use MySQL 5.7
+- Run migrations with migrate.sh (NOTE: This script was removed, use db-migrate now)
+```
+
+**Why:** Contains outdated information and historical comments.
+
+**Good:**
+```
+# Database
+- Use PostgreSQL 15+
+- Run migrations with `npm run db:migrate`
+```
+
+## Unclear Scope
+
+**Bad:**
+```
+Don't use global variables
+```
+
+**Why:** Unclear if this applies to all files, tests, or specific contexts.
+
+**Good:**
+```
+# Code style
+- Avoid global variables in src/ (tests can use them for fixtures)
+```
+
+## Missing Context for Commands
+
+**Bad:**
+```
+Run: make proto
+```
+
+**Why:** No explanation of when or why to run this.
+
+**Good:**
+```
+# After editing .proto files
+- make proto: Regenerate protobuf code
+```
+
+## Over-Capitalization for Emphasis
+
+**Bad:**
+```
+NEVER EVER USE VAR IN JAVASCRIPT CODE!!!
+YOU MUST ALWAYS USE CONST OR LET!!!
+```
+
+**Why:** Excessive caps and punctuation create noise.
+
+**Good:**
+```
+# JavaScript style
+- NEVER use var, use const or let
+```
+
+## Instructions That Should Be Code
+
+**Bad:**
+```
+When rotating PDFs, make sure to:
+1. Load the PDF using pdfplumber
+2. Iterate through each page
+3. Rotate each page by the specified degrees
+4. Save the output
+```
+
+**Why:** Repetitive procedural code should be in a script, not instructions.
+
+**Good:**
+```
+# PDF manipulation
+- Rotate PDFs: python scripts/rotate_pdf.py <input> <degrees> <output>
+```
+
+## Mixing Different Concerns
+
+**Bad:**
+```
+# Instructions
+- Use ES modules
+- The build takes about 5 minutes
+- John prefers arrow functions
+- Run tests before committing
+- I fixed a bug last week where...
+```
+
+**Why:** Mixes style guidelines, historical notes, timing info, and personal preferences.
+
+**Good:**
+```
+# Code style
+- Use ES modules
+- Prefer arrow functions
+
+# Development workflow
+- Run `npm test` before committing
+```