Summary

• Slims root CLAUDE.md from ~994 lines to 54 lines with routing table
• Adds .claude/rules/ for cross-cutting concerns (testing, security, development)
• Adds per-directory CLAUDE.md files for implementation details
• Updates .gitignore to track .claude/commands/ and .claude/rules/
• Updates constitution.md to reference routing table for doc updates
• Adds speckit commands to version control

Motivation

1. Context bloat - Claude loads ~994 lines regardless of relevance, triggering character warnings
2. Merge conflicts - Claude updates CLAUDE.md during work (Recent Changes, HTTP APIs, etc.), causing conflicts when pulling main
3. No routing - Claude didn't know where to put new learnings, defaulted to dumping in root CLAUDE.md

Solution

New Structure

CLAUDE.md                    # 54 lines - essentials + routing table
.claude/rules/
├── testing.md               # Path-scoped: *_test.go, tests/**
├── security.md              # Path-scoped: quarantine/**, isolation/**
└── development.md           # Always loaded: workflow, commits
cmd/mcpproxy/CLAUDE.md       # CLI details
cmd/mcpproxy-tray/CLAUDE.md  # Tray state machine
internal/oauth/CLAUDE.md     # OAuth flows
internal/httpapi/CLAUDE.md   # REST API
internal/server/CLAUDE.md    # MCP protocol
internal/runtime/CLAUDE.md   # Event bus, lifecycle
internal/upstream/CLAUDE.md  # 3-layer client
frontend/CLAUDE.md           # Vue/TypeScript

Test plan

• Start new Claude Code session in this branch
• Verify root CLAUDE.md loads (check with /memory)
• Work on a test file, verify testing.md rules load
• Work on OAuth code, verify internal/oauth/CLAUDE.md loads
• Verify no character limit warnings

Design doc

See docs/plans/2025-12-15-claude-md-restructure.md