mcpField
R
review-claudemd

review-claudemd

github.com/ykdojoAgent workflows10.3k238 installsUpdated 5w ago
Repository

About review-claudemd

Review CLAUDE.md from conversation history is a workflow for Claude users who want to assess project instructions against recent conversations. It analyzes global and local CLAUDE.md files and organizes findings into violations, additions, and potentially outdated guidance.

Key features

  1. 01Locate recent project conversations
  2. 02Compare history with global and local rules
  3. 03Identify instruction violations
  4. 04Suggest local and global additions
  5. 05Flag potentially outdated guidance

Use cases

  1. 01Review project guidance after recurring instruction misses
  2. 02Find project-specific patterns for local CLAUDE.md
  3. 03Assess which global rules need reinforcement
  4. 04Prepare proposed CLAUDE.md edits for discussion

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ykdojo/claude-code-tips --skill review-claudemd

After installing, type/review-claudemdin Claude Code to confirm it loaded.

Details

From the project README

Review CLAUDE.md from conversation history

Analyze recent conversations to improve both global (~/.claude/CLAUDE.md) and local (project) CLAUDE.md files.

Step 1: Find conversation history

The project's conversation history is in ~/.claude/projects/. The folder name is the project path with slashes replaced by dashes.

# Find the project folder (replace / with -)
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lt "$CONVO_DIR"/*.jsonl | head -20

Step 2: Extract recent conversations

Extract the 15-20 most recent conversations (excluding the current one) to a temp directory:

SCRATCH=/tmp/claudemd-review-$(date +%s)
mkdir -p "$SCRATCH"

for f in $(ls -t "$CONVO_DIR"/*.jsonl | head -20); do
  basename=$(basename "$f" .jsonl)
  # Skip current conversation if known
  cat "$f" | jq -r '
    if .type == "user" then
      "USER: " + (.message.content // "")
    elif .type == "assistant" then
      "ASSISTANT: " + ((.message.content // []) | map(select(.type == "text") | .text) | join("\n"))
    else
      empty
    end
  ' 2>/dev/null | grep -v "^ASSISTANT: $" > "$SCRATCH/${basename}.txt"
done

ls -lhS "$SCRATCH"

Step 3: Spin up subagents

Launch parallel subagents to analyze conversations. Each agent should read:

  • Global CLAUDE.md: ~/.claude/CLAUDE.md
  • Local CLAUDE.md: ./CLAUDE.md (if exists)
  • Batch of conversation files

Give each agent this prompt template:

Read:
1. Global CLAUDE.md: ~/.claude/CLAUDE.md
2. Local CLAUDE.md: [project]/CLAUDE.md
3. Conversations: [list of files]

Analyze the conversations against BOTH CLAUDE.md files. Find:
1. Instructions that exist but were violated (need reinforcement or rewording)
2. Patterns that should be added to LOCAL CLAUDE.md (project-specific)
3. Patterns that should be added to GLOBAL CLAUDE.md (applies everywhere)
4. Anything in either file that seems outdated or unnecessary

Be specific. Output bullet points only.

Batch conversations by size:

  • Large (>100KB): 1-2 per agent
  • Medium (10-100KB): 3-5 per agent
  • Small (<10KB): 5-10 per agent

Step 4: Aggregate findings

Combine results from all agents into a summary with these sections:

  1. Instructions violated - existing rules that weren't followed (need stronger wording)
  2. Suggested additions - LOCAL - project-specific patterns
  3. Suggested additions - GLOBAL - patterns that apply everywhere
  4. Potentially outdated - items that may no longer be relevant

Present as tables or bullet points. Ask user if they want edits drafted.

Comments

Markdown supported