/advising-architecture

name: advising-architecture
description: Validates component-type choices for agent system work, classifying knowledge as CLAUDE.md vs rule vs skill vs agent vs hook and checking for conflicts. Use when starting any skill/agent/rule workflow to validate approach. Use when classifying knowledge type. Use when checking for component conflicts.
context: fork
agent: Explore
argument-hint: "[component-description] [intended-type: claudemd|rule|skill|agent|hook]"

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](../../references/task-initialization.md).

**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](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