From ef88271f06de4d8c32a769b2d0c5178d2cbe5551 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:52:25 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++ README.md | 3 + plugin.lock.json | 57 ++++++ skills/claude-md-reflect/SKILL.md | 128 ++++++++++++ .../references/anthropic-best-practices.md | 87 +++++++++ .../references/anti-patterns.md | 182 ++++++++++++++++++ .../scripts/find_claude_md.py | 50 +++++ 7 files changed, 519 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/claude-md-reflect/SKILL.md create mode 100644 skills/claude-md-reflect/references/anthropic-best-practices.md create mode 100644 skills/claude-md-reflect/references/anti-patterns.md create mode 100755 skills/claude-md-reflect/scripts/find_claude_md.py diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..8b5fc2b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "claude-md-reflect", + "description": "Analyze chat history to identify areas for improving CLAUDE.md instruction files", + "version": "1.0.1", + "author": { + "name": "robbyt", + "email": "robbyt@robbyt.net" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..ce9c0d3 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claude-md-reflect + +Analyze chat history to identify areas for improving CLAUDE.md instruction files diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..69eada9 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:robbyt/claude-skills:plugins/claude-md-reflect", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "42cba4fbd41e843273c8780d9bdb8def2ffa6c22", + "treeHash": "5fc90d78089cbbbcfef962965a62ba55cb90c42d4dbfee486e5533d1e136f3a1", + "generatedAt": "2025-11-28T10:28:00.507393Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "claude-md-reflect", + "description": "Analyze chat history to identify areas for improving CLAUDE.md instruction files", + "version": "1.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "d0df383b75f56735f510bb0cffc7ab0bcb66789e4fc001e266c88ee0aa6cc5fe" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "69a66c4d58508ddd8d2e035b1b4f17d643cbe2c3a52dec15c78de39c9bec6560" + }, + { + "path": "skills/claude-md-reflect/SKILL.md", + "sha256": "bb1497c761880d37f463513d8f3d6b5701b8174905a51bdeeb7792c1d384426e" + }, + { + "path": "skills/claude-md-reflect/references/anthropic-best-practices.md", + "sha256": "e3a77d9fc21ac21ec1c2fd7fa6d18b5b02b7177868b809456ca21e60aebf71e4" + }, + { + "path": "skills/claude-md-reflect/references/anti-patterns.md", + "sha256": "7d6861ae431a2122581e517440450b8bb95160420c9e6b9e60914c7b2a005d88" + }, + { + "path": "skills/claude-md-reflect/scripts/find_claude_md.py", + "sha256": "42331c1695e93c115e10b0518e53afe7dd7f3a93bf6246f2370d5ab564982393" + } + ], + "dirSha256": "5fc90d78089cbbbcfef962965a62ba55cb90c42d4dbfee486e5533d1e136f3a1" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/claude-md-reflect/SKILL.md b/skills/claude-md-reflect/SKILL.md new file mode 100644 index 0000000..602e076 --- /dev/null +++ b/skills/claude-md-reflect/SKILL.md @@ -0,0 +1,128 @@ +--- +name: claude-md-reflect +description: Analyze chat history to identify areas for improving CLAUDE.md instruction files. Use when the user says "reflect on CLAUDE.md", "improve CLAUDE.md", or requests analysis of instruction files after a work session. Reviews recent conversation for misunderstandings, inconsistencies, or areas where instructions could be clearer. +--- + +# CLAUDE.md Reflection and Improvement + +## Overview + +This skill analyzes recent chat history and existing CLAUDE.md files to identify improvement opportunities. It follows a three-phase workflow: Analysis, Interaction, and Implementation. + +## When to Use + +Trigger this skill when the user requests: +- "reflect on CLAUDE.md" +- "improve CLAUDE.md" +- Analysis of instruction files after encountering issues + +## Workflow + +### Phase 1: Analysis + +Use the Task tool with subagent_type='general-purpose' to analyze the entire session history. + +**Find all CLAUDE.md files:** +```bash +python scripts/find_claude_md.py +``` + +The script returns paths to all CLAUDE.md files in the repository, sorted by depth (root first). + +**Analyze for:** +- Inconsistencies in Claude's responses vs user expectations +- Misunderstandings of user requests +- Areas where Claude lacked necessary context +- Repetitive corrections from the user +- Common mistakes or confusion patterns +- Instructions that belong in a different CLAUDE.md file + +**Read reference materials:** +- Read `references/anthropic-best-practices.md` for official CLAUDE.md guidelines +- Read `references/anti-patterns.md` for common mistakes to avoid + +### Phase 2: Interaction + +Present findings to the user using the AskUserQuestion tool with checkboxes. + +**For each suggested improvement:** +1. Explain the issue identified in chat history +2. Propose a specific change (add, update, or delete content) +3. Show which CLAUDE.md file to update +4. Explain the rationale and expected impact + +**Format suggestions as:** +- Clear, actionable changes +- Specific text additions or modifications +- NOT vague improvements + +**Example:** +``` +Issue: Claude repeatedly used 'var' instead of 'const' in JavaScript code +Proposal: Add to CLAUDE.md: "NEVER use var in JavaScript, use const or let" +File: ./frontend/CLAUDE.md +Rationale: Prevents repeated corrections for JavaScript variable declarations +``` + +Wait for user approval on each suggestion before proceeding to implementation. + +### Phase 3: Implementation + +For each approved change: + +1. **Identify correct file and section:** + - Root CLAUDE.md: Project-wide guidance + - Subdirectory CLAUDE.md: Component-specific guidance + - User CLAUDE.md (~/.claude/CLAUDE.md): Personal preferences + +2. **Update the file:** + - Add, update, or delete content as approved + - Keep changes minimal and targeted + - Maintain existing structure and formatting + - Use bullet points, not paragraphs + - Add emphasis (NEVER, ALWAYS, IMPORTANT) where critical + +3. **Follow anti-patterns guidance:** + - NO hyperbolic language (crucial, proper, robust, excellent) + - NO vague instructions (write good code, use best practices) + - NO historical comments (we used to do X, now we do Y) + - NO redundant information + - KEEP it concise and actionable + +4. **Verify hierarchy:** + - Root CLAUDE.md should link to subdirectory CLAUDE.md files + - Instructions should be in the most appropriate file for their scope + +## File Organization + +**Root CLAUDE.md:** +- Project-wide guidelines +- Links to subdirectory CLAUDE.md files +- Common commands and workflows + +**Subdirectory CLAUDE.md:** +- Component-specific guidance +- Should be referenced from root CLAUDE.md + +**Example root CLAUDE.md structure:** +``` +# Project Instructions + +## Subdirectories +- Frontend: @frontend/CLAUDE.md +- Backend: @backend/CLAUDE.md + +## Commands +- npm run build: Build all components +- npm test: Run all tests + +## Code Style +- Use 2-space indentation +- NEVER commit directly to main branch +``` + +## Resources + +- `scripts/find_claude_md.py` - Locate all CLAUDE.md files in repository +- `references/anthropic-best-practices.md` - Official Anthropic CLAUDE.md guidelines +- `references/anti-patterns.md` - Common mistakes to avoid diff --git a/skills/claude-md-reflect/references/anthropic-best-practices.md b/skills/claude-md-reflect/references/anthropic-best-practices.md new file mode 100644 index 0000000..7d179e4 --- /dev/null +++ b/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 diff --git a/skills/claude-md-reflect/references/anti-patterns.md b/skills/claude-md-reflect/references/anti-patterns.md new file mode 100644 index 0000000..0a82964 --- /dev/null +++ b/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 +``` + +## 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 +``` diff --git a/skills/claude-md-reflect/scripts/find_claude_md.py b/skills/claude-md-reflect/scripts/find_claude_md.py new file mode 100755 index 0000000..a3bb030 --- /dev/null +++ b/skills/claude-md-reflect/scripts/find_claude_md.py @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +"""Find all CLAUDE.md files in a directory tree.""" + +import os +import sys +from pathlib import Path + +TARGET_FILENAME = "CLAUDE.md" + + +def find_claude_md_files(root_dir="."): + """ + Find all CLAUDE.md files in the directory tree. + + Args: + root_dir: Directory to start searching from (default: current directory) + + Returns: + List of paths to CLAUDE.md files, sorted by depth (root first) + """ + claude_md_files = [] + root_path = Path(root_dir).resolve() + + for dirpath, dirnames, filenames in os.walk(root_path): + if TARGET_FILENAME in filenames: + file_path = Path(dirpath) / TARGET_FILENAME + rel_path = file_path.relative_to(root_path) + claude_md_files.append(str(rel_path)) + + # Sort by depth (root first, then by path) + claude_md_files.sort(key=lambda p: (p.count(os.sep), p)) + + return claude_md_files + + +def main(): + """Main entry point.""" + root_dir = sys.argv[1] if len(sys.argv) > 1 else "." + + files = find_claude_md_files(root_dir) + + if not files: + sys.exit(f"No {TARGET_FILENAME} files found") + + for file_path in files: + print(file_path) + + +if __name__ == "__main__": + main()