Skip to main content

ADR-212: CODITECT.md as Controlled Source with CLAUDE.md Symlink

Status​

Accepted — 2026-02-19

Context​

Problem 1: Customer Control​

Claude Code reads .claude/CLAUDE.md (or CLAUDE.md at project root) as its instruction file. Currently, CLAUDE.md is a regular file in coditect-core/ that gets symlinked to project directories via the protected installation. However:

  • Customers can discover that CLAUDE.md drives Claude Code behavior
  • Nothing prevents a customer from replacing the symlink with their own file
  • A customer-modified CLAUDE.md would bypass CODITECT safety directives, task tracking, session logging, and governance hooks
  • CODITECT's value proposition depends on these controls being active

Problem 2: Token Overhead​

Analysis (2026-02-19) found that three files loaded per conversation total ~7,600 tokens with:

  • Triple duplication of Git Push Safety across core CLAUDE.md, rollout-master CLAUDE.md, and MEMORY.md (~650 bytes wasted)
  • Double duplication of Analysis Preservation, Session Log Location, Document Placement
  • Overexplained protocols adding ~2,050 bytes of rationale that could be trimmed
  • Stale counts (agents: 776 vs actual 805, commands: 377 vs 389, etc.)
  • Missing commands (/moe-agents, /moe-workflow, /moe-judges not in core)
  • 28% reduction possible (~2,165 tokens saved) with zero information loss

A codebase audit found 375 regular CLAUDE.md files vs 99 symlinks:

  • Root-level submodule CLAUDE.md: 76/78 correctly symlinked (97.4%)
  • 171 stale copies inside coditect-dev-generative-ui-development/submodules/
  • 52 archived files, 19 enterprise PCF files, various tool/subdirectory context files

Decision​

1. Rename CLAUDE.md to CODITECT.md​

The canonical content file in coditect-core/ is renamed from CLAUDE.md to CODITECT.md. This file is the single source of truth for all CODITECT framework directives.

coditect-core/
├── CODITECT.md              ← real file (what we edit)
├── CLAUDE.md → CODITECT.md  ← relative symlink (what Claude Code reads)

The installation script (scripts/coditect-core-initial-setup.py) is updated to:

  1. Copy CODITECT.md to the protected installation as a real file
  2. Create CLAUDE.md → CODITECT.md symlink in the protected installation
  3. Create all project-level symlink chains as before
Protected Installation:
  ~/Library/Application Support/CODITECT/core/
  ├── CODITECT.md              ← real file
  ├── CLAUDE.md → CODITECT.md  ← symlink

Project Symlink Chain:
  project/.claude/CLAUDE.md
    → project/.coditect/CLAUDE.md
      → ~/PROJECTS/.coditect/CLAUDE.md
        → ~/.coditect/CLAUDE.md
          → ~/Library/.../core/CLAUDE.md
            → ~/Library/.../core/CODITECT.md

The sync pipeline (scripts/core-sync.py) uses git pull which preserves symlinks. The framework-sync atomic re-clone (scripts/framework-sync.py) already handles .claude and .coditect symlink cleanup; it must also preserve the CLAUDE.md → CODITECT.md symlink (not dereference it).

4. Optimize Content​

The content of CODITECT.md (formerly CLAUDE.md) is optimized:

  • Remove YAML frontmatter (not used by Claude, only MoE classifier)
  • Merge Agent System section: add /moe-agents, /moe-workflow, /moe-judges; drop "Common:" agent name list
  • Trim overexplained protocol rationale (Analysis Preservation: 38→15 lines, Session Logging: 24→14, Task ID: 35→20)
  • Fix stale component counts to current values
  • Add missing commands to Quick Commands table

5. Deduplicate Across Files​

  • Rollout-master CLAUDE.md: Remove duplicated Git Push Safety section and Agent System section (now in core CODITECT.md)
  • MEMORY.md: Remove duplicated Git Push Safety, Analysis Preservation, Session Log Location, Document Placement sections

Consequences​

Positive​

  • CODITECT controls the instruction set — CLAUDE.md is always a symlink, never a standalone file customers can edit
  • Clear ownership signal — the real file is named CODITECT.md, making it obvious this is CODITECT-managed
  • ~28% token reduction (~2,165 tokens saved per conversation) through dedup and trimming
  • Single source of truth — one file to edit, changes propagate everywhere via symlinks
  • Missing MoE commands added — /moe-agents, /moe-workflow, /moe-judges now discoverable

Negative​

  • Symlink chain depth — 5-hop chain from project to CODITECT.md content (functional but harder to debug)
  • Framework-sync update required — must not dereference the CLAUDE.md symlink during atomic re-clone
  • Git behavior — git stores symlinks as target paths; cloning on a new machine without installation gives a broken CLAUDE.md symlink until install runs
  • Backward compatibility — existing projects with hardcoded references to CLAUDE.md content (not path) are unaffected; those referencing the file directly may need symlink refresh

Neutral​

  • No customer impact — customers already interact with CLAUDE.md via symlinks; the underlying rename is invisible
  • Third-party submodules — repos like agent-labs/ have their own CLAUDE.md which is not CODITECT-controlled; these remain as regular files

Implementation​

Files to Modify​

FileChange
coditect-core/CLAUDE.mdRename to CODITECT.md, create CLAUDE.md → CODITECT.md symlink
coditect-core/CODITECT.mdContent optimization (trim, dedup, add missing commands, fix counts)
scripts/coditect-core-initial-setup.pyHandle CODITECT.md + CLAUDE.md symlink in protected installation
scripts/framework-sync.pyPreserve CLAUDE.md → CODITECT.md symlink during atomic re-clone
scripts/check-project-symlinks.pyAdd CLAUDE.md symlink validation
CLAUDE.md (rollout-master)Remove duplicated Git Push Safety and Agent System sections
MEMORY.mdRemove duplicated directives, move context-specific content to topic files

Migration​

  1. Rename and create symlink in coditect-core
  2. Update install/sync scripts
  3. Run /sync to propagate to protected installation
  4. Run check-project-symlinks.py --fix to update all projects
  5. Clean up rollout-master CLAUDE.md and MEMORY.md
  • ADR-057 — CODITECT installation and onboarding architecture
  • ADR-114 — User data directory separation
  • ADR-182 — Post-sync integrity scanning
  • Analysis: internal/analysis/claude-md-optimization/claude-md-optimization-analysis-2026-02-19.md