This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Laarma は CSA AARM 仕様 の Python プロトタイプ実装。AI エージェントのツール呼び出しを実行前にインターセプト・評価・記録する。
このファイルは索引であり、設計判断・リポジトリの地図・使い方の内容そのものは持たない。それぞれの正典（下記）を参照すること。各正典は現在の実装に合わせて維持される living document であり、本ファイルはそこへ案内するだけに徹する。
- 設計判断（なぜこの設計か、どう実装すべきか） →
docs/design/の各設計メモ。メモの一覧と要旨は README.md の「設計メモ（docs/design/）」 にある（ここには列挙しない。二重メンテを避けるため）。 - リポジトリの地図（構成・層の分離・処理フロー・主要モジュールの責務） → README.md。
- セットアップ・使い方・各機能の詳細（環境変数・静的ポリシー定義・監査ログ・権限スコープ・Embedding・ベンチマーク・DEFER ハンドリングなど） → README.md の「詳しい使い方（docs/）」 からたどれる
docs/*.md。
食い違ったときの原則: 本ファイルの記述と上記の正典が食い違う場合は、正典を優先し、その相違を報告すること。本ファイルは案内・索引であり、方針転換の直後などに一時的に古くなっている可能性がある。
これは正典化できない「作業上の約束事」であり、本ファイルに残す。
テスト基盤を変えない: 回帰・シナリオテストは my_project/benchmark.py のシナリオ追加（benchmark_data.jsonl にケース追加、LLM 必須なら pipeline_only: true）で行う。新たに pytest 等のテストファイルやテストフレームワークを追加しない。これは確定した方針であり、判断の背景と将来導入する場合の基準は docs/design/laarma-testing-infrastructure.md にある。テスト基盤を変えたくなったら、実装に入る前に相談すること。
設計メモを正典として扱う: コードと設計メモが食い違っていると気づいたら、勝手にどちらかへ寄せず、相違を報告すること。設計判断を伴う変更（アーキテクチャ・コンポーネントの責務・処理フローの変更など）をするときは、まず docs/design/ の該当メモを参照し、メモに無い判断が必要なら相談する。
成果物は経緯非依存・自己完結で書く: コード・ドキュメント・コミットメッセージなどリポジトリに残る成果物は、その時々の作業経緯を知らない将来の読者にとって、それ単体で読めるように書く。実装作業の経緯や言い訳を成果物本文に持ち込まない。具体的には:
- 作業経緯・言い訳を書かない: ドキュメントは現在の状態を現在形で記述する。「〜に変更した」「このステップで実装した」「〜のスコープ外」のような開発経緯は、最終読者（リポジトリを読む人）に関係がないので本文に書かない。変更の経緯は PR や Issue が担う。例: 設計メモの見出しを「現状（PR-X 完了後）」とせず「現状」と書く。
- ローカルな呼び名を裸で使わない: 特定 Issue 内の便宜的な呼称（「PR-2」「PR-4」のようなステップ名）は、リポジトリ全体から見ると参照先が一意でない。成果物に書くなら最低限
Issue #NN の PR-Xのように Issue 番号で修飾するか、複数箇所で使うなら冒頭で一度「以下のステップは Issue #NN で実施」と宣言してその文脈下に置く。経緯参照そのものを避けて現在形で書けるならそれが最善。 - 結論だけでなく導出が追えるようにする: 設計メモに結論を書くときは、その結論がどの前提から導かれたかが読者に追えるようにする。典拠（仕様の節・既存メモ）が特定の主体や条件についての記述なら、それを一般化した結論を書く際は一般化の根拠も添える。
権限: merge と delete はリポジトリオーナーが行う。Claude Code は file の読み書き・issue・branch・PR 作成までを担い、merge / ブランチ削除はしない。