explaining-rules

Step 1: Load Rule Index

Load the complete rule index to discover all available rules:

• @.claude/context/rule-index.json

The index contains metadata for all rules in .claude/rules-master/ and .claude/archive/.

Note: If the index is empty or missing, it needs to be generated first:

• Run pnpm index-rules or node scripts/generate-rule-index.mjs
• This scans all rules and creates the index file

Step 2: Analyze Target File or Query

Determine what needs explanation:

• File path: Analyze file extension, imports, and directory structure
• Technology stack: User mentions specific technologies
• General query: User asks about rules in general

Step 3: Detect Technologies

For file-based queries, detect technologies using:

• File extension (.tsx → TypeScript, React)
• Import statements (next → Next.js, react → React)
• Directory structure (app/ → Next.js App Router)
• Framework-specific patterns

See reference/technology-detection.md for detailed detection patterns.

Step 4: Query Rule Index

Use the index's technology_map to find relevant rules:

// Pseudocode
const detectedTech = ['nextjs', 'react', 'typescript'];
const relevantRules = [];

detectedTech.forEach(tech => {
  const rules = index.technology_map[tech] || [];
  relevantRules.push(...rules);
});

// Remove duplicates
const uniqueRules = [...new Set(relevantRules)];

Step 5: Load Relevant Rules

Load only the relevant rule files (progressive disclosure):

• Master rules take priority (from .claude/rules-master/)
• Archive rules supplement (from .claude/archive/)
• Load 5-10 most relevant rules, not all 1,081

Step 6: Explain Rules

For each relevant rule, explain:

• What it covers: Main purpose and scope
• Why it applies: Connection to the file/query
• Key requirements: Most important standards
• Examples: Code examples showing compliance

Use the template in reference/rule-explanation-template.md for consistent output.