エージェントに渡した参照メモの7割は届いていませんでした — head で切る運用の限界を測った記録

#!/usr/bin/env python3
"""notes_pack.py — 参照メモをセクション単位でバイト予算内に詰める"""
import re
import sys
from pathlib import Path
 
HEADING = re.compile(r"^##\s+(.+)$")
 
 
def split_sections(text: str):
    """先頭の前文と ## 単位の節に分解する"""
    lines = text.splitlines(keepends=True)
    preamble, sections = [], []
    current = None
    for line in lines:
        m = HEADING.match(line)
        if m:
            if current:
                sections.append(current)
            current = {"title": m.group(1).strip(), "body": [line]}
        elif current:
            current["body"].append(line)
        else:
            preamble.append(line)
    if current:
        sections.append(current)
    for s in sections:
        s["text"] = "".join(s["body"])
        s["bytes"] = len(s["text"].encode("utf-8"))
    return "".join(preamble), sections
 
 
def pack(path: Path, budget: int, keep_titles=()):
    text = path.read_text(encoding="utf-8")
    preamble, sections = split_sections(text)
    out, used, dropped = [], len(preamble.encode("utf-8")), []
 
    # ① 明示的に必須と指定された節を先に確保する
    pinned = [s for s in sections if any(k in s["title"] for k in keep_titles)]
    rest = [s for s in sections if s not in pinned]
 
    for s in pinned + rest:
        if used + s["bytes"] <= budget:
            out.append(s)
            used += s["bytes"]
        else:
            dropped.append(s["title"])  # ② 途中で切らず、節ごと落とす
 
    body = preamble + "".join(s["text"] for s in out)
    return body, used, dropped
 
 
if __name__ == "__main__":
    src = Path(sys.argv[1])
    budget = int(sys.argv[2]) if len(sys.argv) > 2 else 20000
    keep = sys.argv[3].split(",") if len(sys.argv) > 3 else []
    body, used, dropped = pack(src, budget, keep)
    sys.stdout.write(body)
    # ③ 落とした節は必ず stderr に出す（沈黙させない）
    if dropped:
        sys.stderr.write(
            f"[notes_pack] {src.name}: {used}/{budget} bytes, "
            f"dropped {len(dropped)} sections: {', '.join(dropped[:5])}\n"
        )

<!-- notes-priority: pinned -->
## 端末別の分岐（毎回必要）
 
<!-- notes-priority: fresh -->
## 2026-07-13 の更新

#!/usr/bin/env bash
# notes_preflight.sh — 参照メモの実在・非空・必須キーを実行前に確認する
set -euo pipefail
 
NOTES="${1:?usage: notes_preflight.sh <notes-dir>}"
FAIL=0
 
check() {
  local file="$1"; shift
  local path="${NOTES}/${file}"
 
  if [ ! -f "$path" ]; then
    echo "⚠️ 参照メモ欠落: ${path}"; FAIL=$((FAIL + 1)); return
  fi
  if [ ! -s "$path" ]; then
    echo "⚠️ 参照メモが空: ${path}"; FAIL=$((FAIL + 1)); return
  fi
  # 必須キー（この節が無いメモは壊れているとみなす）
  for key in "$@"; do
    if ! grep -qF "$key" "$path"; then
      echo "⚠️ 必須セクション欠落: ${path} → ${key}"; FAIL=$((FAIL + 1))
    fi
  done
  echo "✅ ${file} ($(wc -c < "$path") bytes)"
}
 
check "release_steps.md" "## 端末別の分岐" "## ロールバック"
check "known_issues.md"  "## 未解決"
 
if [ "$FAIL" -gt 0 ]; then
  echo "🛑 ${FAIL} 件の参照メモ異常。エージェントを起動せずに終了します"
  exit 1
fi