archcodex CLAUDE.md

Claude Code Instructions for ArchCodex

This project uses ArchCodex for architectural constraints.

BEFORE MODIFYING CODE

STOP. Call this MCP tool first:

archcodex_context { "projectRoot": "/absolute/path/to/project", "module": "src/path/to/module/" }

projectRoot must be an absolute path where .arch/ exists (contains the SQLite database).

This gives you everything in one call:

• Project Rules - Layer hierarchy + shared constraints across all architectures
• Modification Order - DEFINES → IMPLEMENTS → ORCHESTRATES
• 🔴N Impact - How many files break if you change this one
• Layer Boundaries - CAN/CANNOT import lists
• Entity Schemas - Fields, relationships, behaviors (inline)
• Architecture Constraints - forbid, patterns, require, all hints
• Validation Command - Run after changes

Workflow

1. archcodex_context       ← GET FULL CONTEXT FIRST (module or entity)
2. Read tool               ← READ files (code content)
   archcodex_read          ← GET per-file constraints (auto-injected via pre-read hook)
3. Write code              ← Follow modification order, respect constraints
4. archcodex_check         ← VALIDATE AFTER CHANGES (auto-run via post-write hook)

Note: archcodex_read returns only architectural data (constraints, boundaries, hints) — never file content. Use the agent's native Read tool for code content. The pre-read hook auto-injects constraints when reading src/ files.

MCP Tools

When	Tool Call
Before modifying	archcodex_context { "projectRoot": "/path", "module": "src/dir/" }
Before creating	archcodex_discover { "projectRoot": "/path", "query": "description" }
After changes	archcodex_check { "projectRoot": "/path", "files": ["src/**/*.ts"] }
Entity work	archcodex_context { "projectRoot": "/path", "entity": "EntityName" }
Task guidance	archcodex_action { "projectRoot": "/path", "query": "add order action" }
Verify wiring	archcodex_feature_audit { "projectRoot": "/path", "mutation": "duplicateOrder", "entity": "orders" }
Scaffold spec	archcodex_spec_scaffold_touchpoints { "projectRoot": "/path", "specId": "spec.orders.duplicateOrder", "entity": "orders" }