CLAUDE.md Architect skill for Claude Code

#!/usr/bin/env python3
"""Audit Claude Code memory files (CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md).

Usage:
    python3 audit_claude_md.py [repo_root] [--max-lines N] [--no-user]

Reports per file: lines, approximate tokens (own + imports), broken @imports,
backticked paths that do not exist, generic filler phrases, secret-looking strings,
lines duplicated across files, and whether CLAUDE.local.md is gitignored.

Exit code 1 on errors (broken imports, secret-like strings, a file over twice the line
limit), else 0. Standard library only.
"""
from __future__ import annotations

import argparse
import re
import subprocess
import sys
from pathlib import Path

SKIP_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build", ".next", "target", "__pycache__"}
GENERIC = [
    "clean code", "best practices", "meaningful names", "well-documented", "readable code",
    "follow conventions", "write tests for", "be careful", "high quality", "maintainable",
    "keep it simple", "dry principle", "solid principles",
]
SECRET_RES = [
    re.compile(r"sk-[A-Za-z0-9_-]{20,}"), re.compile(r"AKIA[0-9A-Z]{16}"),
    re.compile(r"gh[pousr]_[A-Za-z0-9]{30,}"), re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"),
    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
    re.compile(r"(?i)(password|secret|api[_-]?key|token)\s*[:=]\s*['\"]?[A-Za-z0-9/+_-]{12,}"),
]
IMPORT_RE = re.compile(r"(?:^|\s)@((?:~/|\.{0,2}/)?[\w.-]+(?:/[\w.-]+)*\.\w+)")
CODE_SPAN_RE = re.compile(r"`([^`\n]+)`")


def strip_code(text: str) -> str:
    text = re.sub(r"```.*?```", "", text, flags=re.S)
    return CODE_SPAN_RE.sub("", text)


def find_files(root: Path, include_user: bool) -> list[Path]:
    found: list[Path] = []
    for p in root.rglob("*"):
        if any(part in SKIP_DIRS for part in p.relative_to(root).parts[:-1]):
            continue
        if not p.is_file():
            continue
        rel = p.relative_to(root).as_posix()
        if p.name in ("CLAUDE.md", "CLAUDE.local.md") or re.search(r"(^|/)\.claude/rules/.+\.md$", rel):
            found.append(p)
    user = Path.home() / ".claude" / "CLAUDE.md"
    if include_user and user.is_file():
        found.append(user)
    return sorted(set(found))


def resolve_import(src: Path, target: str) -> Path:
    if target.startswith("~/"):
        return Path.home() / target[2:]
    return (src.parent / target).resolve()


def import_tokens(path: Path, seen: set[Path], depth: int = 0) -> tuple[int, list[str]]:
    """Return (tokens of imported files, list of broken import descriptions)."""
    if depth > 5:
        return 0, [f"{path}: import chain deeper than 5"]
    total, broken = 0, []
    for target in IMPORT_RE.findall(strip_code(path.read_text(encoding="utf-8", errors="replace"))):
        dest = resolve_import(path, target)
        if not dest.is_file():
            broken.append(f"@{target}")
            continue
        if dest in seen:
            continue
        seen.add(dest)
        total += len(dest.read_text(encoding="utf-8", errors="replace")) // 4
        sub_total, sub_broken = import_tokens(dest, seen, depth + 1)
        total += sub_total
        broken += sub_broken
    return total, broken


def looks_like_path(s: str) -> bool:
    if " " in s or s.startswith(("http", "$", "-", "@")) or any(c in s for c in "*<>{}|=()"):
        return False
    return "/" in s and (re.search(r"\.\w{1,6}$", s) is not None or s.endswith("/"))


def is_ignored(root: Path, path: Path) -> bool | None:
    try:
        r = subprocess.run(["git", "-C", str(root), "check-ignore", "-q", str(path)], capture_output=True)
        return r.returncode == 0 if r.returncode in (0, 1) else None
    except FileNotFoundError:
        return None


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("root", nargs="?", default=".")
    ap.add_argument("--max-lines", type=int, default=150)
    ap.add_argument("--no-user", action="store_true")
    args = ap.parse_args()
    root = Path(args.root).resolve()
    files = find_files(root, not args.no_user)
    if not files:
        print(f"No memory files found under {root}. Start from /init, then prune.")
        return 0

    errors: list[str] = []
    warnings: list[str] = []
    line_owner: dict[str, Path] = {}
    grand = 0
    print(f"{'lines':>5} {'tokens':>7} {'+import':>7}  file")
    for f in files:
        text = f.read_text(encoding="utf-8", errors="replace")
        lines = text.splitlines()
        own = len(text) // 4
        imp, broken = import_tokens(f, {f})
        grand += own + imp
        label = f.relative_to(root).as_posix() if root in f.parents else str(f)
        print(f"{len(lines):>5} {own:>7} {imp:>7}  {label}")

        for b in broken:
            errors.append(f"{label}: broken import {b}")
        limit = args.max_lines if f.name == "CLAUDE.md" and f.parent in (root, root / ".claude") else args.max_lines * 2 // 3
        if len(lines) > 2 * args.max_lines:
            errors.append(f"{label}: {len(lines)} lines (more than twice the {args.max_lines}-line target)")
        elif len(lines) > limit:
            warnings.append(f"{label}: {len(lines)} lines (target <= {limit})")
        if imp > 2000:
            warnings.append(f"{label}: imports add ~{imp} tokens to every session")

        lower = text.lower()
        for phrase in GENERIC:
            if phrase in lower:
                warnings.append(f"{label}: generic phrase '{phrase}' (Claude does this anyway; delete or make concrete)")
        for rx in SECRET_RES:
            if rx.search(text):
                errors.append(f"{label}: secret-like string matching {rx.pattern[:30]}... (remove and rotate)")
        for span in CODE_SPAN_RE.findall(text):
            if looks_like_path(span):
                candidates = [root / span.lstrip("./"), f.parent / span]
                if not any(c.exists() for c in candidates):
                    warnings.append(f"{label}: referenced path `{span}` not found (stale?)")
        emph = len(re.findall(r"\b(IMPORTANT|MUST|NEVER|ALWAYS|CRITICAL)\b", text))
        if emph > 5:
            warnings.append(f"{label}: {emph} emphasis words; keep emphasis for 2-3 rules")
        for ln in lines:
            norm = re.sub(r"\s+", " ", ln.strip(" -*#>").lower())
            if len(norm) < 25:
                continue
            if norm in line_owner and line_owner[norm] != f:
                warnings.append(f"{label}: duplicates a line in {line_owner[norm].name}: '{norm[:60]}'")
            line_owner.setdefault(norm, f)
        if f.name == "CLAUDE.local.md" and is_ignored(root, f) is False:
            errors.append(f"{label}: CLAUDE.local.md is not gitignored")

    print(f"\nTotal: ~{grand} tokens across {len(files)} files (own text + imports)")
    print("(nested CLAUDE.md files load only when Claude works in that directory)")
    for e in errors:
        print(f"ERROR   {e}")
    for w in warnings:
        print(f"WARNING {w}")
    print(f"Result: {'FAIL' if errors else 'PASS'} ({len(errors)} errors, {len(warnings)} warnings)")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())