Codebase DNA Guardian

A Senior Architect Guardian that extracts and enforces the tribal knowledge embedded in a codebase. Every mature project has unwritten rules — naming conventions, error handling patterns, import styles, folder structures, test strategies — that only experienced team members know. This skill captures those rules as a machine-readable DNA profile and enforces them continuously.

Why this exists

New code in an existing project should look like it was written by the team's most consistent, experienced developer. Not by a generalist AI that introduces "better" patterns from other projects. The cost of inconsistency is real: cognitive load, review friction, onboarding time, subtle bugs from mixed conventions. This skill prevents that.

Core principles

1. DNA First, Code Second. Before writing any new code in a project with a DNA profile, read it. If the new code would contradict it, explain the conflict and propose a DNA-compliant alternative.

2. Mimic, Don't Innovate. When adding features, mimic existing patterns. Do not introduce patterns from other projects unless the user explicitly asks for a migration.

3. Severity-Aware Intervention. Not every convention is equally important. See the severity tiers below — hard rules get proactive intervention, soft conventions get a footnote, preferences get silently applied.

4. Incremental Scanning. Real codebases are too large to read entirely. The scan strategy samples representative files, not everything.

5. Hierarchical DNA. Monorepos and multi-service projects have root-level DNA (shared conventions) and per-service DNA (overrides). The skill supports this natively.

Severity tiers

Every DNA rule has one of three severity levels. This determines how the Guardian intervenes:

When generating DNA, assign a tier to every rule. When uncertain, default to SOFT — it informs without blocking.

Commands

/dna-scan — Extract project DNA

Performs an incremental scan of the codebase and generates a DNA profile.

Phase 1: Skeleton Discovery (fast, no file reading)

Run these commands to build a structural map without reading file contents:

# Project root structure (2 levels)
find . -maxdepth 2 -type f \( -name "*.json" -o -name "*.toml" -o -name "*.yaml" -o -name "*.yml" -o -name "*.lock" \) | head -30

# Framework detection
cat package.json 2>/dev/null | head -40
cat tsconfig.json 2>/dev/null
cat pyproject.toml 2>/dev/null
cat go.mod 2>/dev/null
cat Cargo.toml 2>/dev/null

# Folder structure
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' | head -60

# File naming patterns (just names, not contents)
find ./src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) 2>/dev/null | head -80

From this, determine:

• Language and framework
• Monorepo vs single project
• Folder philosophy (feature-based, layer-based, domain-driven)
• File naming convention (from file names alone)

Phase 2: Representative Sampling (targeted file reading)

Do NOT read 100 files. Instead, sample strategically:

1. Config files (3-5): tsconfig.json, eslint*, prettier*, .editorconfig, framework config
2. Entry points (2-3): main.ts, app.ts, index.ts, server.ts
3. One complete vertical slice (4-6 files): Pick one feature and read its controller/route → service → repository/model → test → types. This reveals the full architectural pattern.
4. Error handling samples (2-3): Search for catch, Error, throw, Result patterns
5. Test files (2-3): Reveal test framework, naming, mocking strategy
6. Shared utilities (2-3): src/lib/, src/utils/, src/common/ — reveals helper patterns

Total: ~15-20 files max. Enough to extract DNA without hitting context limits.

Phase 3: Pattern Extraction

From the sampled files, extract DNA markers in these categories:

• A. Naming: File naming, component naming, variable casing, constant casing, type/interface naming
• B. Architecture: Folder structure, layer separation, state management, data access pattern, auth pattern
• C. Error Handling: Custom error classes, Result pattern vs try/catch, error boundaries, logging library
• D. Testing: Framework, file naming/location, mocking strategy, assertion style
• E. Dependencies: Actually used vs installed, competing libraries, wrapper patterns
• F. Imports: Absolute vs relative, path aliases, barrel files, import ordering
• G. API Contracts: Response envelope shape, pagination pattern, validation approach, status code usage
• H. Async Patterns: Promise vs async/await, concurrency control, queue/job patterns

Phase 4: Generate DNA Profile

Write the DNA profile to .claude/dna.md (single project) or .claude/dna/root.md + .claude/dna/{service}.md (monorepo). See templates/dna-template.md for the exact format.

Include in the DNA file:

• Scan metadata (date, files sampled, project hash)
• Each rule with: ID, severity tier, description, example, counter-example
• A ## Zombie Dependencies section listing packages with no detectable imports (mark as "suspected" — verify with depcheck/knip)
• An ## Architectural Drift Zones section listing areas of the codebase with internal inconsistency
• A ## Staleness section with last scan date and invalidation hints

Phase 5: Confidence Check

After generating, do a quick validation — pick 2-3 files NOT in the sample set and check if the extracted rules hold. If a rule contradicts >1 file, downgrade it from HARD to SOFT or note it as "inconsistently applied."

/dna-check [path] — Audit files against DNA

Read .claude/dna.md, then analyze the target file(s):

1. Load DNA rules
2. Read target file(s) — if a directory, sample up to 10 files
3. Check each rule against each file
4. Report violations grouped by severity

Output format:

DNA Audit: src/services/user-service.ts

🔴 HARD VIOLATIONS (fix before merge):
  Line 24: Direct HTTP call via axios — DNA-H3 requires apiClient wrapper
  → Replace with: import { apiClient } from '@/lib/api-client'

🟡 SOFT VIOLATIONS (convention drift):
  Line 1-5: Named export without barrel re-export — DNA-S7 prefers barrel files
  → Consider adding to src/services/index.ts

✅ 18 rules checked, 16 compliant
⏰ DNA last scanned: 12 days ago (consider re-scan if major changes landed)

/dna-refactor [path] — Auto-fix violations

1. Load DNA, read target file(s)
2. Identify all violations
3. Show a summary of planned changes and ask for confirmation
4. Apply fixes preserving business logic
5. If files are renamed, update imports across the codebase
6. Re-run /dna-check to verify

Never apply refactoring without showing the plan first. Business logic changes are never part of a DNA refactor — only structural/stylistic changes.

/dna-report — Health dashboard

Generate a project-wide health summary:

Codebase DNA Health Report
Generated: 2026-05-28

Files sampled: 22 / 187 total
Rules extracted: 24 (8 HARD, 11 SOFT, 5 PREF)

Consistency Score: 84% (20/24 rules consistently followed)

🔴 HARD violations found: 3
  - 2x raw SQL in controller layer (DNA-H4)
  - 1x unhandled async error (DNA-H2)

🟡 SOFT drift detected: 6
  - 4x camelCase file names in src/services/ (DNA-S1 expects kebab-case)
  - 2x console.log instead