CR-2026-03-25: CLAUDE.md Modernization

Change Summary

Field Value

Change ID

CR-2026-03-25-claudemd-001

Requested By

Self

Target Date

Next session

Systems Affected

~/.claude/CLAUDE.md

Risk Level

Low

Rollback Time

< 1 minute (restore from backup)

Category

Normal

Problem Statement

The global CLAUDE.md (772 lines) contains outdated content and missing references to modern Claude Code features implemented in this session.

Outdated Sections

Section Location Issue

"2-Week Journey"

Lines 90-94

Written when user was 2 weeks into Linux - skill level has advanced significantly

"Documentation Strategy"

Lines 362-373

Mentions Principia → domus-* migration as ongoing - likely complete

"Common Attributes table"

Lines 480-506

Hardcoded IP/MAC values embedded in CLAUDE.md - should reference antora.yml as source of truth

Missing Modern Features

The following Claude Code features are implemented but NOT documented in CLAUDE.md:

Feature Location Implemented

Custom Skills

~/.claude/skills/

/deploy, /worklog

Custom Agents

~/.claude/agents/

doc-auditor.md

Path-Specific Rules

~/.claude/rules/

asciidoc.md, lua-nvim.md

Hooks Architecture

~/.claude/hooks.json

4 active hooks (backup, shellcheck, asciidoc-attrs, session-start)

Keybindings

~/.claude/keybindings.json

Custom shortcuts

Settings Deny Rules

~/.claude/settings.json

Secrets protection (redundant with FORBIDDEN section)

Current State (Audit)

~/.claude/ Contents
~/.claude/
├── CLAUDE.md              # 772 lines - needs modernization
├── settings.json          # 85 lines - consolidated, clean
├── hooks.json             # 65 lines - 4 active hooks
├── keybindings.json       # 21 lines - custom shortcuts
├── skills/                # 2 skills implemented
│   ├── deploy/SKILL.md
│   └── worklog/SKILL.md
├── agents/                # 1 agent implemented
│   └── doc-auditor.md
├── rules/                 # 2 rules implemented
│   ├── asciidoc.md
│   └── lua-nvim.md
└── hooks/                 # Hook scripts
    └── validate-asciidoc-attrs.sh  # 173 lines

Implementation Plan

Phase 1: Remove Outdated Content

Action Current New

"2-Week Journey" section

"User has been in Linux for 2 weeks…​"

Remove timeline, keep CLI mastery methodology

Principia migration mention

"From: Principia/02_Assets…​"

"All documentation in domus-* ecosystem"

Common Attributes table

Hardcoded values in CLAUDE.md

Reference: "See component antora.yml for current values"

Phase 2: Add Modern Features Section

Add new section: ## Claude Code Configuration Architecture

## Claude Code Configuration Architecture

The full configuration is documented in domus-captures:
- **Reference:** xref:projects/personal/claude-code-features/index.adoc[]

### Quick Reference

| Component | Purpose | Location |
|-----------|---------|----------|
| **Skills** | On-demand workflows | `~/.claude/skills/*/SKILL.md` |
| **Agents** | Specialized subagents | `~/.claude/agents/*.md` |
| **Rules** | Path-specific instructions | `~/.claude/rules/*.md` |
| **Hooks** | Lifecycle automation | `~/.claude/hooks.json` |
| **Settings** | Permissions, sandbox | `~/.claude/settings.json` |

### Active Skills

- `/deploy` - Push spoke repo + trigger domus-docs rebuild
- `/worklog` - Create WRKLOG with 8 partials

### Active Hooks

- **PreToolUse**: Auto-backup before Edit/Write
- **PostToolUse**: ShellCheck + AsciiDoc attribute validation
- **SessionStart**: Professional environment confirmation

Phase 3: Consolidate Secrets Protection

The FORBIDDEN section and settings.json deny rules are redundant. Keep FORBIDDEN section (guidance) and note that settings.json enforces it:

## FORBIDDEN: Secrets Access

**NEVER access user secrets directly.**

This is enforced by `settings.json` deny rules:
- `Read(./.env)`, `Read(~/.secrets/*)`
- `Bash(age -d:*)`, `Bash(gopass show:*)`

Phase 4: Update Skill Level

Change from:

User has been in Linux for 2 weeks, typing commands daily...

To:

User is building Linux proficiency through deliberate practice.
Focus: awk, sed, grep, find, xargs mastery.

Verification

# Line count should decrease (removed redundancy)
wc -l ~/.claude/CLAUDE.md
# Expected: ~700 lines (from 772)

# Modern features section present
grep -c "Claude Code Configuration" ~/.claude/CLAUDE.md
# Expected: 1

# Skills reference present
grep -c "/deploy" ~/.claude/CLAUDE.md
# Expected: >= 1

Rollback

# Backup created before changes
cp ~/.claude/CLAUDE.md ~/.claude/backups/CLAUDE.md.$(date +%Y%m%d-%H%M%S).bak

# Restore if needed
cp ~/.claude/backups/CLAUDE.md.*.bak ~/.claude/CLAUDE.md

Related Documents

Notes

The goal is to:

  1. Remove drift - Outdated timeline and migration status

  2. DRY principle - Remove hardcoded values that exist elsewhere

  3. Cross-reference - Point to PRJ document for detailed configuration

  4. Maintain intent - Keep core philosophy sections intact