Advising Architecture

Advising Architecture

Overview

Advising architecture IS classifying knowledge into the correct Claude Code component.

One concept, one location. Misclassification wastes tokens (global rule that should be scoped) or misses enforcement (advisory instruction that should be a deterministic hook).

Core principle: CLAUDE.md = broad project instructions. Rules = path-scoped conventions. Skills = on-demand capabilities. Agents = isolated workers. Hooks = deterministic enforcement.

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

1. Understand the request
2. Scan for conflicts
3. Classify component type
4. Provide recommendation

Announce: "Created 4 tasks. Starting execution..."

Component Hierarchy (Priority Order)

1. CLAUDE.md (highest)       - Broad project instructions
   └─ Loaded every session (expensive — keep < 200 lines)
   └─ Only what Claude can't figure out from code
   └─ Specific, verifiable instructions with MUST/NEVER emphasis

2. Rules (.claude/rules/)    - Path-scoped conventions
   └─ Loaded only when Claude reads a file matching paths:
   └─ No paths = loaded at launch, every session
   └─ < 50 lines each (token cost)
   └─ Frontmatter: paths (YAML array of globs)

3. Skills (.claude/skills/)  - Capabilities (how to do)
   └─ Loaded on-demand by Claude OR invoked via /skill-name
   └─ Progressive disclosure: SKILL.md + references/
   └─ Gerund naming: writing-skills, not write-skill
   └─ Frontmatter: name, description, when_to_use,
      argument-hint, arguments, allowed-tools,
      disallowed-tools, model, effort, context, agent,
      background, hooks, paths, shell, user-invocable,
      disable-model-invocation

4. Agents (.claude/agents/)  - Isolated context workers
   └─ Invoked via Agent tool
   └─ Frontmatter: name, description, tools,
      disallowedTools, model, maxTurns, skills,
      permissionMode, effort, isolation, background,
      memory, mcpServers, hooks, color, initialPrompt
   └─ context/agent are SKILL fields — invalid here

5. Hooks (.claude/hooks/)    - Automated quality gates
   └─ Exit code 2 = block action
   └─ < 5 seconds execution
   └─ Static checks only

Classification Decision Tree

Does it apply BROADLY to all project work?
├─ Yes → CLAUDE.md instruction
│   Examples: Communication style, build commands, architecture
│   Key: Keep < 200 lines, specific and verifiable
│
└─ No → What type of knowledge?
    │
    ├─ HOW TO DO something (capability)?
    │   → SKILL in skills/
    │   Naming: gerund form (writing-*, creating-*)
    │   Structure: Overview → Routing → Tasks (+ Red Flags / Task Initialization as needed)
    │   Routing pattern:
    │     ├─ Contains decision points → Tree
    │     ├─ Part of multi-skill workflow → Chain
    │     ├─ Simple, single task → Node (context: fork, model: haiku)
    │     └─ Internal steps only → Skill Steps
    │   Consider: context: fork for analysis-oriented skills
    │   Consider: model selection (haiku for fast, opus for complex)
    │
    ├─ WHAT TO DO (convention for specific files)?
    │   → RULE in .claude/rules/
    │   Use when: different paths need different conventions
    │     e.g., monorepo packages with different frameworks,
    │     src/ vs tests/ with different coding standards,
    │     frontend (React) vs backend (Express) rules
    │   paths: glob isolates rules to matching files only
    │   Format: paths as YAML array of globs
    │   Keep < 50 lines, imperative language
    │
    ├─ ISOLATED WORKER (needs separate context)?
    │   First consider: built-in subagent types (Explore, Plan, general-purpose)
    │   Then consider: skill with context: fork
    │   Last resort: custom AGENT in agents/
    │   CRITICAL: isolated context = no conversation history
    │   → Design argument-hint/prompt to pass sufficient context
    │
    └─ AUTOMATED CHECK (quality gate)?
        → HOOK in .claude/hooks/
        Python script, exit 2 to block
        Configure in settings.json

Best Practices per Component

CLAUDE.md

• < 200 lines — loaded every session; only what Claude can't figure out from code
• Specific and verifiable; use MUST/NEVER sparingly
• NOT for: linter-enforceable rules (hooks), path-scoped (rules), workflows (skills)

Rules (.claude/rules/)

• < 50 lines each; use paths: YAML array to scope to file patterns
• Imperative language; best for monorepo/frontend-vs-backend conventions
• NOT for: procedures (skills), broad instructions (CLAUDE.md)

Skills (.claude/skills/)

• On-demand loading = token efficient; use context: fork for analysis tasks
• Use model to optimize cost; disable-model-invocation: true for manual-only
• NOT for: conventions (rules), broad instructions (CLAUDE.md)

Agents (.claude/agents/)

• First consider built-in types (Explore/Plan/general-purpose), then context: fork
• Tools declared upfront — subagents CANNOT request at runtime
• NOT for: guidance (skills), conventions (rules)

See references/model-selection.md for agent three-layer model selection guide.

Hooks (.claude/hooks/)

• Deterministic enforcement; exit code 2 = block; keep < 5 seconds
• Best for: lint checks, format validation, commit message enforcement
• NOT for: complex workflows (skills), advisory guidelines (CLAUDE.md/rules)

Task 1: Understand the Request

Goal: Clarify what is being created or modified.

Questions to answer:

• What knowledge is being encoded?
• Does it apply broadly to all project work, or only to specific paths?
• Does it teach a capability (how to) or enforce a convention (what to)?
• Does it need deterministic enforcement (hook) or advisory guidance (CLAUDE.md/rule)?

Verification: Can state the knowledge type in one sentence.

Task 2: Scan for Conflicts

Goal: Check existing components for overlaps.

Process:

1. Check CLAUDE.md for related instructions
2. Check .claude/rules/ for overlapping conventions
3. Check skills/ for duplicate capabilities
4. Check agents/ for overlapping responsibilities

Verification: Listed all related existing components (or confirmed none).

Task 3: Classify Component Type

Goal: Apply decision tree to determine correct component type.

Verification: Classification matches decision tree logic.

Task 4: Provide Recommendation

Goal: Deliver structured recommendation.

Output format:

## Architecture Assessment

**Request:** [What you're trying to create]

**Classification:** [CLAUDE.md / rule / skill / agent / hook]

**Rationale:** [Why this classification]

**Location:** [Exact path where it should go]

**Conflicts Found:**
- [List any existing components that overlap, or "None"]

**Key Constraints:**
- [Important rules for this component type]

**Recommendation:** [Proceed / Reconsider / Merge with existing]

Verification: Recommendation includes all fields above.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "This is both a rule AND a skill"
• "CLAUDE.md is overkill, a rule is fine"
• "Global rule is fine without paths:"
• "Skip conflict scan, it's obviously new"
• "Agent is needed" (before considering built-in types or context: fork)

All of these mean: You're about to misclassify. Follow the decision tree.

Common Rationalizations