LLM の利用

ナビゲーション: ガイド | ドキュメントルート

Keleusma のソースやスクリプトに対して AI コーディングアシスタント (Claude Code、Codex、Cursor、Aider など) を使用する運用者向けのガイダンスです。以下の助言は、一般的な Rust コードで訓練された AI ツールが最初の試行で誤りがちなパターンを扱い、加えて反復時間を短縮する実用的なプロンプトを示します。

この文書は AI を操作する運用者向けに書かれています。作業開始時に AI セッションへ直接与えるコンテキストとしても有用です。より広いエコシステムにおける AI 直接投入用コンテキストファイルの慣例は、プロジェクトルートの AGENTS.md と llms.txt です。いずれもより深いガイダンスとしてこの文書を参照しています。

想定読者

2 つの運用者プロファイルがこのガイドの恩恵を受けます。

組み込みアプリケーション向けに Keleusma スクリプトを書く組み込み者。Keleusma の表層は十分に特異であるため、LLM が生成したスクリプトは最初の試行でしばしば検証に失敗します。
Rust で Keleusma ランタイムを編集する貢献者。ランタイムの no_std + alloc の姿勢と保守的検証の立場は、いくつかの一般的な Rust の慣用に反します。

いずれのプロファイルも同様のコンテキストを必要とします。以下で指摘するパターンは、この区分を越えて当てはまります。

あらゆる AI セッションでの読解順序

変更を加える前に、セッションの開始時に AI にこれらの文書を読ませてください。

プロジェクトの慣例とセッションごとのプロトコルについては AGENTS.md。
AI 固有のパターンの落とし穴については、この文書。
設計の背後にある理由については docs/architecture/LANGUAGE_DESIGN.md を参照してください。
アーキテクチャ上の決定の歴史的記録については docs/decisions/RESOLVED.md を参照してください。「なぜこのように行われたのか」という質問のほとんどはここで回答されています。
現在のスプリントの状態については docs/process/TASKLOG.md を、最新の AI から人間への引き継ぎについては docs/process/REVERSE_PROMPT.md を参照してください。

あらゆる AI セッションに与える有用な最初のプロンプト:

Please read AGENTS.md, llms.txt, docs/guide/LLM_USAGE.md, the process documents
at docs/process/, then walk the knowledge graph under docs/. Summarise what
you learned in three to five paragraphs before proceeding to any task.

「進める前に要約する」ことで、AI が斜め読みではなく実際に読んだことを示すよう強制します。

AI ツールが誤りがちなパターン

以下の項目は、このコードベースでの AI 支援作業において繰り返し表面化してきました。パターンは文書化されており、AI はそれを読むことが期待されます。

`no_std + alloc` のみ

Keleusma のランタイムクレートは alloc を伴う no_std を対象とします。標準ライブラリは利用できません。

AI の最初の反射はいくつもの点で誤りがちです。それぞれを指定された alloc の等価物に置き換えてください。

誤り (std のみ)	正しい (no_std + alloc)
`std::collections::HashMap`	`alloc::collections::BTreeMap`
`std::collections::HashSet`	`alloc::collections::BTreeSet`
`std::fs`、`std::io`、`std::process`	利用不可。ホストが登録するネイティブ関数として表面化する
`std::sync::Mutex`、`std::sync::RwLock`	利用不可。ランタイムはシングルスレッド
`Box::leak`、`Box::pin`	`alloc::boxed::Box`から利用可能だが、リークパターンは却下される
`std::time::Instant`、`std::time::SystemTime`	利用不可。クロックアクセスはホストがネイティブで提供
`println!`、`eprintln!`	利用不可。`println`ネイティブはホストが登録

keleusma-cliクレートはstdにリンクするので、バイナリレイヤでこれらのAPIを使えます。ランタイムクレートでは使えません。

テストやCLIでも、HashMapよりBTreeMapを使ってください。テストスイートが強制するバイト同一のバイトコード性質は、安定したイテレーション順に依存しています。ハッシュマップのイテレーション順はRustバージョンを跨いで安定せず、1つのバージョン内でも容量が増えるとずれることがあります。1つの機械で通るテストが、イテレーション順が観測可能な出力に漏れる場合、別の機械で失敗するかもしれません。

非決定論の他の源にも同じことが適用されます — 浮動小数点の縮約、std::hash::DefaultHasher、システム時間、明示的にシードされていない乱数生成器、read_dirによるファイルイテレーション順。AIがこれらのどれかを導入したら、プロンプトが何を求めていたかに関わらず、その変更は間違いです。

保守的検証スタンス

安全な検証器はWCETとWCMUの解析を打ち破る構文を却下します。具体的には:

すべての再帰はコンパイル時に却下されます — 再帰呼び出しが証明可能に終了する場合でも。解析は有向非巡回コールグラフを必要とします。
クロージャは型検査の段階で却下されます — クロージャ呼び出しによる動的ディスパッチが呼び出しごとのコストモデルを打ち破るからです。
dyn Traitはほとんどの位置で却下されます — 仮想ディスパッチが呼び出し地点ごとのコスト解析を打ち破るからです。
平坦な制御フローのオペコード(Jmp、Branch)は命令セットに存在しません。ブロック構造化された形式(If、Else、EndIf、Loop、EndLoop、Break、BreakIf)だけが認められています。
静的に抽出できない反復回数を持つループは、厳格モードの有界反復解析(R38)によって却下されます。

AIの自然な反射は、アルゴリズムがそう要求するように見えたときに、これらの構文を使うことです。正しい応答は、アルゴリズムを書き換えてワークスタックパターン(再帰ではなく明示的なスタック)、列挙型ベースのディスパッチ(dyn Traitではなく)、または固定反復ループ(無界ではなく)を使うことです。

検証器の診断メッセージは却下された構文に名前を付けて、docs/guide/WHY_REJECTED.mdの対応するガイダンスを指し示します。検証器を緩めて診断を黙らせないでください。却下は設計の一部です。

トレイト境界付きジェネリクス対トレイトオブジェクト

AIが&dyn Traitに手を伸ばすところでは、fn foo<T: Trait>(x: T)またはfn foo<T: Trait>(x: &T)を好んでください。モノモーフ化する形式は認められ、動的形式は保守的検証スタンスによってほとんどの位置で却下されます。

これはRust組み込みのベストプラクティスと同じ姿勢ですが、AIはパターンを認識しないかもしれません。作業が新しいトレイト面を伴うなら、プロンプトの最初にこの慣習を引用してください。

永続状態は`data`ブロックに置く。モジュールレベルのstaticではなく

RustコードをポートするときのAIの一般的な反射は、実行ごとの状態のためにモジュールレベルのstaticまたはlazy_staticを導入することです。Keleusmaでは、ループ反復を跨ぐ永続状態はプログラムが宣言したdataブロックに属し、GetDataとSetDataを通してアクセスされます。ホストが下にあるストレージを所有し、スクリプトはスロット番号で読み書きします。言語レベルのモジュールレベル可変状態はありません。

セッションごとのプロトコル

docs/process/PROCESS_STRATEGY.md に従い、各セッションは特定の形式を持ちます。

現在のタスク状態については docs/process/TASKLOG.md を読んでください。
最後の AI から人間への引き継ぎについては docs/process/REVERSE_PROMPT.md を読んでください。
進める前に人間のプロンプトを待つ。

各タスクを完了したあと:

TASKLOG.mdのタスク状態を更新する。
検証、質問、懸念、意図する次のステップでREVERSE_PROMPT.mdを上書きする。
運用者が明示的に頼んだときだけコミットする。そうでなければ変更は未コミットのままにする。

このプロトコルはAGENTS.mdとCLAUDE.mdに文書化されていますが、再度述べる価値があります。このプロジェクトでのAIセッションは厳格なセッションごとの契約で動きます。

スクラッチディレクトリ

tmp/を一時ファイル(下書き、プローブ出力、スクラッチスクリプト、統合待ちの設計仕様)に使ってください。tmp/とsecret/の内容は慣習でgitignoreされています。secret/は権限状態に関わらず決してコミットされてはいけないファイルに使ってください。

AIの一般的な反射は、作業をリポジトリのルートかdocs/の新しいサブディレクトリに置くことです。下書き資料にはtmp/が正しいです。完成した資料には、適切なdocs/サブディレクトリが正しいです。パターンは — 下書きはtmp/、レビュー後にdocs/に昇格、です。

役立つプロンプトパターン

下記のパターンは、開放的なプロンプトよりも高品質な出力を生みます。

「まず読み、要約し、それから進める」パターン

Please read [specific document paths]. Summarise what you learned in three
to five paragraphs. Then [the actual task].

要約-最初ステップは、AIが実際にドキュメントを読んだことを示すよう強制します。また、関連するコンテキストが読み込まれたことを運用者が見える形で示します。

「実装の前に設計」パターン

Please produce a design document at tmp/<topic>.md before writing any code.
The design should cover [the specific concerns]. Length budget two pages.
Identify any places where the design does not map cleanly onto existing
patterns in the codebase.

非自明な作業のために、設計-前-実装はレビュー可能な成果物を生み、方向転換のコストを減らします。このパターンはtmp/enrolled_keys_execution.mdとtmp/call_site_identifier.mdで作業例として確立されています。

アルゴリズム作業のための「構造境界」パターン

Please implement [algorithm] using the work-stack pattern documented in
docs/research/r3_1_recursion_to_iteration.md. The verifier rejects
recursion; do not use recursive helper functions. Declare the stack
capacity statically.

ワークスタックパターン(または他のKeleusma特有のパターン)への明示的な参照は、AIが再帰的なRustイディオムにデフォルトで戻るのを防ぎます。

「完了と主張する前に検証する」パターン

After implementing, run the full verification suite:
  cargo test && cargo clippy --tests -- -D warnings
Do not report the task complete until both pass.

検査に基づいて成功を主張するのではなく、AIに実際に検証を走らせるよう強制します。

このガイドが何でないか

このガイドはKeleusmaのチュートリアルではありません。言語が初めての運用者はGETTING_STARTED.mdから始めるべきです。このガイドはAIツールのチュートリアルでもありません。使っているAIアシスタントへの運用者の慣れを前提としています。

このガイドは網羅的ではありません。新しいパターンはAI支援セッションごとに表面化します。ここに文書化されていない繰り返しのAI失敗モードが見つかった場合、セクションを追加してください。これは生きたドキュメントです。

The Keleusma Guide