Smart Rules

Smart Rules

A skill that analyzes user prompts and efficiently loads only relevant rule/guide documents.

Key Features

• Auto-initialization: Scans project documents and auto-generates config file on first invocation
• Config-based: Category-document mapping defined in project-specific smart-rules.yaml
• Efficient loading: Skips if no match, loads only what's needed
• Dual invocation: Auto-execute before tasks or manual /smart-rules command
• Post-TodoWrite trigger: Analyzes todo content and loads relevant rules after TodoWrite

⛔ CRITICAL: Auto-Invocation Rules

AI MUST automatically invoke smart-rules in these situations:

1. After TodoWrite Tool Usage

When AI uses the TodoWrite tool, AI MUST invoke smart-rules to analyze the todo content and load relevant rules:

[AI uses TodoWrite tool]
        ↓
[Analyze todo content keywords]
        ↓
[Smart Rules] Loaded documents for: [matched categories based on todo content]

Example:

TodoWrite: "Export 다이얼로그 UI 구현"
        ↓
Keywords: Export, 다이얼로그, UI, 구현
        ↓
[Smart Rules] Loaded 3 documents for categories: [ui, design, patterns]
  - Docs/UX/IA.md
  - Docs/UX/DesignSystem/Components.md
  - Docs/Patterns/Flutter-Desktop-Window-Management-Pattern.md

Why? 에이전트가 작업할 todo와 관련된 규칙을 미리 숙지하여 올바른 패턴과 컨벤션을 따르도록 합니다.

2. Before Implementation Tasks

When user requests feature implementation, bug fix, or code changes:

[User requests implementation]
        ↓
[Smart Rules] Analyzing keywords...
[Smart Rules] Loaded documents for: [coding, patterns, ...]

Auto-Invocation Triggers

Commands

Workflow

1. Initialization (init) - When config file missing

[1. Detect Missing Config]
    └─ Check if smart-rules.yaml exists
           ↓
[2. Scan Project Documents]
    └─ Scan standard paths:
       - .claude/rules/*.md
       - Docs/**/*.md
       - .claude/CLAUDE.md, CLAUDE.md
       - README.md
           ↓
[3. Analyze & Categorize]
    └─ Classify discovered documents by category
           ↓
[4. Extract Keywords]
    └─ Extract keywords from document titles/headers
           ↓
[5. Generate Config]
    └─ Create smart-rules.yaml file
    └─ Report generated config to user

2. Document Loading - When config file exists

[1. Load Config]
    └─ Read smart-rules.yaml
           ↓
[2. Analyze Prompt]
    └─ Extract keywords from user prompt
           ↓
[3. Match Categories]
    └─ Match keywords → categories
    └─ Check composite categories
           ↓
[4. Skip if No Match]
    └─ Skip if no matches found
           ↓
[5. Load Documents]
    └─ Load matched category documents
    └─ Remove duplicates, apply max_documents limit
           ↓
[6. Report]
    └─ Output loaded document list

Auto-categorization Rules

Documents are auto-classified by filename/path patterns during scanning:

Excluded Categories

AI MUST NOT scan or load documents for these categories:

These files should be excluded from scanning:

• .claude/rules/labeling.md
• .claude/rules/history.md
• Docs/Labels/**/*.md
• Docs/History/**/*.md
• Docs/Brain/**/*

Config File Schema (smart-rules.yaml)

version: 1

# 스캔된 문서 경로 (자동 생성 시 기록)
scanned_paths:
  - .claude/rules/
  - Docs/

# 옵션
options:
  max_documents: 5          # 최대 로드 문서 수
  auto_invoke: true         # 작업 시작 전 자동 실행 여부
  show_loaded_report: true  # 로드된 문서 목록 출력 여부

# 카테고리 정의
categories:
  category_name:
    keywords:
      - 키워드1
      - keyword2
    documents:
      - path/to/document1.md
      - path/to/document2.md

# 복합 카테고리 (여러 카테고리 조합)
composites:
  composite_name:
    keywords:
      - 복합 키워드
    includes:
      - category1
      - category2

Usage Examples

Example 1: Feature Implementation Request

User: "로그인 화면을 구현해줘"

AI Analysis:
- Keywords: 로그인, 화면, 구현
- Matched: ui, design, coding

[Smart Rules] Loaded 3 documents for categories: [ui, design, coding]
  - Docs/UX/IA.md
  - Docs/UX/DesignSystem/Components.md
  - Docs/Index/CODING_CONVENTIONS.md

Example 2: Specific Category Load

User: "/smart-rules task"

[Smart Rules] Category 'task' loaded:
  - .claude/rules/task-management.md

Example 3: No Match

User: "git commit 해줘"

[Smart Rules] No matching rules for this task. Proceeding without rule documents.

Output Format

On Match Success

[Smart Rules] Loaded N documents for categories: [cat1, cat2]
  - path/to/doc1.md
  - path/to/doc2.md

On No Match

[Smart Rules] No matching rules for this task. Proceeding without rule documents.

On Initialization

[Smart Rules] Initializing...
Scanned paths: .claude/rules/, Docs/
Found N documents across M categories.

Generated: .smart-rules.yaml

Categories created:
  - architecture (2 docs)
  - coding (2 docs)
  - ui (3 docs)
  ...

Limitations

Config File Location

IMPORTANT: Config file is stored in project root, SEPARATELY from skill definition.

.smart-rules.yaml                     ← Project-specific config (generated at root)
.claude/skills/smart-rules/SKILL.md   ← Skill definition only (do NOT touch)

Why Separate?

• Skill folder is managed by Droid (synced, updated, reset)
• Config file is project-specific and persists across skill updates
• Prevents "folder already exists" conflicts during init

Init Behavior

• /smart-rules init checks for .smart-rules.yaml in project root
• If missing → scans project and creates .smart-rules.yaml at root
• If exists → uses existing config (no conflict with skill folder)
• /smart-rules rescan deletes .smart-rules.yaml and rescans