AGENTS.md を厚くするほどルールが守られなくなった — 遵守率を計測して指示を削るまで

# tools/adherence/rules.py
# AGENTS.md の各ルールに 1 対 1 で対応する検証関数を並べる。
# ここに書けないルールは AGENTS.md にも書かない、という方針の受け皿にする。
 
import re
from dataclasses import dataclass
from typing import Callable
 
@dataclass
class Violation:
    rule_id: str
    file: str
    line: int
    excerpt: str
 
@dataclass
class Rule:
    id: str            # AGENTS.md 側にも同じ ID を書いて対応を明示する
    description: str
    applies_to: str    # ファイルパスの正規表現
    check: Callable[[str, str], list]
 
def no_console_log(path: str, content: str) -> list:
    out = []
    for i, line in enumerate(content.splitlines(), start=1):
        # コメント行の説明文まで拾わないよう、行頭の呼び出しに限定する
        if re.search(r'(?<!//\s)\bconsole\.(log|debug)\s*\(', line):
            out.append(Violation("R-001", path, i, line.strip()))
    return out
 
def function_length_limit(path: str, content: str, limit: int = 30) -> list:
    out = []
    lines = content.splitlines()
    start, name, depth = None, None, 0
    for i, line in enumerate(lines, start=1):
        m = re.match(r'\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)', line)
        if m and start is None:
            start, name, depth = i, m.group(1), 0
        if start is not None:
            depth += line.count("{") - line.count("}")
            if depth <= 0 and i > start:
                if (i - start) > limit:
                    out.append(Violation("R-004", path, start,
                                         f"{name}: {i - start} 行 (上限 {limit})"))
                start, name = None, None
    return out
 
def no_any_type(path: str, content: str) -> list:
    out = []
    for i, line in enumerate(content.splitlines(), start=1):
        # 意図的な any は `// allow-any:` の理由コメントで明示する運用にしている
        if re.search(r':\s*any\b', line) and "allow-any:" not in line:
            out.append(Violation("R-002", path, i, line.strip()))
    return out
 
RULES = [
    Rule("R-001", "console.log を本番コードに残さない",
         r"^src/(?!.*\.test\.).*\.(ts|tsx)$", no_console_log),
    Rule("R-002", "any 型を使わない",
         r"^src/.*\.(ts|tsx)$", no_any_type),
    Rule("R-004", "関数は 30 行以内",
         r"^src/.*\.(ts|tsx)$", function_length_limit),
    # ... 19 個ぶん
]

# tools/adherence/measure.py
import json
import re
import subprocess
from datetime import datetime, timezone
from rules import RULES
 
def changed_files(base: str = "HEAD~1") -> list:
    out = subprocess.run(
        ["git", "diff", "--name-only", "--diff-filter=d", base, "HEAD"],
        capture_output=True, text=True, check=True,
    )
    return [p for p in out.stdout.splitlines() if p]
 
def read_at_head(path: str) -> str:
    out = subprocess.run(["git", "show", f"HEAD:{path}"],
                         capture_output=True, text=True)
    return out.stdout if out.returncode == 0 else ""
 
def measure(base: str = "HEAD~1") -> dict:
    files = changed_files(base)
    per_rule = {r.id: {"applicable": 0, "violated": 0,
                       "description": r.description} for r in RULES}
    violations = []
 
    for path in files:
        content = read_at_head(path)
        if not content:
            continue
        for rule in RULES:
            if not re.match(rule.applies_to, path):
                continue
            # 「適用対象になった回数」を分母にする。
            # 対象外のファイルまで分母に入れると遵守率が甘く出る。
            per_rule[rule.id]["applicable"] += 1
            found = rule.check(path, content)
            if found:
                per_rule[rule.id]["violated"] += 1
                violations.extend(found)
 
    for rid, s in per_rule.items():
        s["adherence"] = (
            None if s["applicable"] == 0
            else round(1 - s["violated"] / s["applicable"], 3)
        )
 
    scored = [s for s in per_rule.values() if s["adherence"] is not None]
    overall = (round(sum(s["adherence"] for s in scored) / len(scored), 3)
               if scored else None)
 
    return {
        "measured_at": datetime.now(timezone.utc).isoformat(),
        "commit": subprocess.run(["git", "rev-parse", "HEAD"],
                                 capture_output=True, text=True).stdout.strip(),
        "files_changed": len(files),
        "overall_adherence": overall,
        "per_rule": per_rule,
        "violations": [v.__dict__ for v in violations],
    }
 
if __name__ == "__main__":
    result = measure()
    with open("adherence.jsonl", "a") as f:
        f.write(json.dumps(result, ensure_ascii=False) + "\n")
    print(f"overall={result['overall_adherence']} "
          f"violations={len(result['violations'])}")