When Only the Back Half of a Subfolder CLAUDE.md Is Ignored, Count Characters, Not Bytes

# Pin the locale to UTF-8 and count characters (correct for Japanese too)
LC_ALL=C.UTF-8 wc -m path/to/CLAUDE.md
 
# Some systems have no C.UTF-8. Try ja_JP.UTF-8 or en_US.UTF-8 instead
locale -a | grep -i utf

#!/usr/bin/env python3
"""List the character counts of CLAUDE.md and .claude/rules/*.md against the on-demand limit.
Usage: python3 instr_size.py <directory where you start Claude Code> [--limit 40000]
Exit code 1 if anything is OVER."""
import os, sys
 
SKIP = {"node_modules", ".git", ".next", "dist", "build"}
 
def has_paths_frontmatter(text):
    if not text.startswith("---"):
        return False
    head = text.split("---", 2)[1] if text.count("---") >= 2 else ""
    return any(line.strip().startswith("paths:") for line in head.splitlines())
 
def classify(rel, text):
    parts = rel.split(os.sep)
    name = parts[-1]
    if name in ("CLAUDE.md", "CLAUDE.local.md"):
        return "always" if len(parts) == 1 else "on-demand"
    if ".claude" in parts and "rules" in parts:
        nested = parts.index(".claude") > 0
        return "on-demand" if (nested or has_paths_frontmatter(text)) else "always"
    return None
 
def main(root, limit):
    rows, over = [], False
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in SKIP]
        for fn in filenames:
            p = os.path.join(dirpath, fn)
            rel = os.path.relpath(p, root)
            if not (fn in ("CLAUDE.md", "CLAUDE.local.md")
                    or (fn.endswith(".md") and f"{os.sep}rules{os.sep}" in p
                        and ".claude" in rel.split(os.sep))):
                continue
            with open(p, encoding="utf-8", errors="replace") as f:
                text = f.read()
            kind = classify(rel, text)
            if kind is None:
                continue
            chars = len(text)
            flag = "OK"
            if kind == "on-demand":
                if chars > limit:
                    flag, over = "OVER", True
                elif chars > limit * 0.8:
                    flag = "NEAR"
            rows.append((chars, len(text.encode("utf-8")), text.count("\n") + 1, flag, kind, rel))
    for chars, nbytes, lines, flag, kind, rel in sorted(rows, reverse=True):
        print(f"{chars:>8} chars {nbytes:>8} B {lines:>5} lines  {flag:<5} {kind:<9} {rel}")
    return 1 if over else 0
 
if __name__ == "__main__":
    limit = 40_000
    args = sys.argv[1:]
    if "--limit" in args:
        i = args.index("--limit"); limit = int(args[i + 1]); del args[i:i + 2]
    sys.exit(main(args[0] if args else ".", limit))

   41000 chars    41000 B   774 lines  OVER  on-demand app/CLAUDE.md
   34000 chars   100342 B   830 lines  OK    always    .claude/rules/api.md
   20000 chars    59026 B   488 lines  OK    on-demand app/sub/CLAUDE.md
   12230 chars    36032 B   302 lines  OK    on-demand .claude/rules/scoped.md
    9000 chars    26562 B   220 lines  OK    always    CLAUDE.md

#!/bin/sh
# .git/hooks/pre-commit  (don't forget chmod +x)
# Block the commit if any on-demand instruction file is over 40,000 characters
python3 tools/instr_size.py . --limit 40000 || {
  echo "pre-commit: a CLAUDE.md is over the limit. Split it into rules or trim it." >&2
  exit 1
}

---
paths:
  - "src/api/**"
---
 
# Rules for the API layer
 
- Never swallow an error; return it to the caller.
- Always put a timeout on outbound calls.