AIワークフロー

このプロジェクトは Claude Code で構築されました。「AIで構築」という主張の多くはラベルを貼るだけで終わります。ここではその全体像をお見せします：AIが何を知っているか、セッションがどう機能するか、実際のプロンプトはどのようなものか、そして人間がどこで線を引くのか。ご自身でAIを使って開発している方、あるいは単純にそれが実際にどういうものか興味がある方にとって、この文書はきっと参考になるはずです。

AIが知っていること

Claude Code には、セッションをまたいでコンテキストを引き継ぐ永続的なメモリファイルがあります。毎回コードベースを探索し直す代わりに、前回の続きから作業を始められます。以下がその内容です（機密情報は除去済み）：

プロジェクトのアイデンティティ

アプリ名、ソースの場所、ライセンス、アプリ識別子
フォーク関係：アップストリームは Francisco Salgueiro による En Croissant で、私たちは独自にフォークを維持しています
フォークが存在する理由：アップストリームのメンテナーがTTS機能を辞退しました。これは当然のことです — 同じプロジェクトに対する異なるビジョンです

ビルドルール

pnpm のみ — npm を使うと vanillaExtract が壊れます（実行時に白い画面、エラーなし、何も表示されない）
Node.js 22+ が必要（Vite 7 は crypto.hash を必要とします）
コミット前に必ず pnpm format && pnpm lint:fix を実行
バイナリを上書きする前にアプリを閉じること（“Text file busy”）
ソースディレクトリを移動した後は cargo clean で古いパス参照をクリア

アーキテクチャの知識

どのファイルがどの機能を担当しているか（アトムは atoms.ts、ツリーナビゲーションは tree.ts、TTSエンジンは tts.ts）
すべてのTTSアトムに getOnInit: true が必要な理由（React がサブスクライブする前に store.get() で命令的に読み取るため）
オーディオキャッシュの仕組み（provider:voiceId:lang:text をキーとして使用）
chessground の座標修正はCSS側で行っており、ライブラリのフォークではない
データレイアウト：何がどこにあるか、何がシンボリックリンクか、何がアプリの再起動後も保持されるか

知らないこと

メモリにはAPIキー、パスワード、認証情報は含まれていません。それらの保存場所（localStorage のアトム名）は参照しますが、値そのものは決して含みません。AIは設定からキーを読み取るコードを生成しますが、実際のシークレットを見たり扱ったりすることはありません。

AIに伝えていること

メモリファイル以外に、Claude Code にはシステムに組み込まれたルールがあります：

過剰設計しない。 直接リクエストされた変更のみを行う。バグ修正の際に周囲のコードを整理する必要はない。3行の類似コードは、時期尚早な抽象化よりも良い。
URLを推測しない。 リンクやエンドポイントを捏造しない。
編集前に読む。 読んでいないコードへの変更を提案しない。
作成より編集を優先。 絶対に必要でない限り、新しいファイルを作成しない。
セキュリティ脆弱性を作らない。 インジェクション、XSS、OWASP トップ10の問題に注意する。
不確実なときは質問する。 指示が曖昧な場合、推測せずに質問する。
二度測って一度切る。 破壊的な操作（force push、reset —hard、ファイル削除）には明示的な人間の承認が必要。

良いプロンプトの書き方

AIとのやり取りが有用になるか、フラストレーションの元になるかの違いは、ほぼ常にプロンプトにあります。

欲しいものを具体的に伝えてください。「バグを直して」ではなく、「TTSキャッシュキーにプロバイダー名が含まれていないため、ElevenLabs から Google に切り替えると、新しい音声を生成する代わりにキャッシュされた ElevenLabs の音声が再生されてしまう」のように。

AIが持っていないコンテキストを含めてください。 AIはコードを読めますが、あなたの頭の中は読めません。「ユーザーから盤面の座標が逆だと報告があった」よりも、「chessgroundBaseOverride.css のCSSでランクとファイルが入れ替わっている — Francisco のオリジナルでは逆になっていた」の方が有用です。

制約を明示してください。「新しいファイルを作成しない」「既存のアトムパターンを使う」「APIキーなしで動作する必要がある」は、AIにガードレールを伝えます。

やってほしくないことを伝えてください。「起こり得ないケースのエラーハンドリングを追加しない」「周囲のコードをリファクタリングしない」は、AIの最も一般的な失敗モードである過剰設計を防ぎます。

パターンは：意図 + コンテキスト + 制約です。これをマスターすれば、AIは劇的に有用になります。

プランモード：ある Claude を使って別の Claude にプロンプトを出す

Claude Code には「プランモード」があり、思考と実行を分離します。プランモードでは、AIがファイルを読み、コードベースを探索し、計画を作成しますが、コードは書きません。計画をレビューし、調整してから、実装モードに切り替えてAIに実行させます。

なぜこれがうまくいくのでしょうか？コーディングタスクで最も難しい部分はコードを書くことではないからです。どのコードを書くべきか — どのファイルを変更するか、どのパターンに従うか、どのエッジケースが存在するか — を見極めることが最も難しいのです。プランモードは、一行のコードが書かれる前に、その問いに全力を注ぎます。

このプロジェクトからの例：Help メニューを再構築して Language セレクターを追加した際、プランモードの会話で Tauri のメニューの仕組み、既存のアトム、ドキュメントビューアーがリソースパスをどう解決するか、確認ダイアログAPIの形を探索しました。実装モードに切り替える頃には、AIは変更の完全なマップを持っていました。無駄な試行錯誤はありませんでした。

本質的に、AIの一つのインスタンスをシニアアーキテクトとして、もう一つを開発者として使っているのです。同じモデルで、異なる役割です。

セッションの仕組み

典型的なセッションは以下のようになります：

人間が意図を述べる。「KittenTTS セクションにキャッシュの注意書きを追加して。」「PostHog のテレメトリを削除して。」「品質評価が間違っている、正しい内容はこれ。」
AIが関連ファイルを読む。 ファイルの中身を推測しません。読んで、現在の状態を理解してから、変更を提案します。独立した複数のファイルは並列で読み取ります。
AIが変更を行う。 既存ファイルへの的確な編集です。書き直しではなく、周囲をすべて保持した外科的な修正です。
人間がレビューする。 すべての編集はディスクに書き込まれる前に表示されます。人間が承認、却下、または方向転換します。「いや、それは柔らかすぎる — 本当にひどいと言って。」「その段落を上に移動して。」「それは私の意図と違う。」
指示されたときにコミットする。 AIが自発的にコミットすることはありません。人間が「コミットして」や「コミットしてプッシュして」と言います。コミットには Co-Authored-By: Claude Opus 4.6 が含まれます — 常に明記され、決して隠されません。

コンテキストウィンドウとセーブステート

すべてのAI会話にはコンテキストウィンドウがあります — 一度にメモリに保持できるテキストの総量です。会話が十分に長くなると、古いメッセージは新しい内容のために圧縮されます。

2つの戦略があります：会話を集中させる（1つのタスクにつき1つの会話）、そしてセーブステートを使う（Claude Code は会話をJSONLファイルとして保存し、完全なコンテキストを復元して再開できます）。メモリファイルは別の目的を持っています — すべての会話を超えて存続する永続的なナレッジベースです。

AIの提案と実際にリリースされるもの

AIの最初の提案が最終版になることはめったにありません。典型的なやり取りは以下の通りです：

AIが妥当な内容をドラフトする
人間が「企業的すぎる」「もっと直接的に」「それは間違い、理由はこう」と言う
AIが調整する
人間が承認する

テイスト、トーン、最終判断は常に人間のものです。AIはベロシティを担当します — ファイルを読み、コンテキストを理解し、メモリに保持できるコードベース全体にわたって正確な編集を行います。人間はジャッジメントを担当します — 何を構築するか、どう感じるべきか、いつ止めるか。

スキルとスラッシュコマンド

Claude Code は「スキル」をサポートしています — .claude/commands/ ディレクトリにマークダウンファイルとして保存された再利用可能なプロンプトです。/translate-docs のようにスラッシュコマンドで呼び出します。

このプロジェクトでは /translate-docs スキルを使用して、ドキュメントの複数言語への翻訳を自動化しています。スキルファイルには完全な指示が含まれています：どのファイルを翻訳するか、どの形式を使うか、コードブロックやリンクをどう扱うか、どのトーンを維持するか。毎回すべてを説明する代わりに、/translate-docs と入力するだけで、AIは正確に何をすべきか把握します。

スキルは情報だけでなく、プロセスをエンコードします。テストの実行、デプロイ、PRレビュー、変更履歴の更新など、あらゆる繰り返しワークフローに対してスキルを構築できます。

コーディング原則

原則の完全なドキュメントは、リポジトリの .claude/01_UNIVERSAL_PRINCIPLES.md にあります。Robert C. Martin の Clean Code（2008年）に AI 時代への追加を加えたところから始まりました。その後、何が今でも通用し、何が通用しないかについて、率直な議論を行いました。

時代を超えて通用するもの

意図を明らかにする名前。 常に。永遠に。
関数は一つのことを行う。 本当の原則はサイズではなく、一貫性です。
副作用なし。 今でもほとんどのバグの原因です。
コメントは「何を」ではなく「なぜ」を説明する。
単一責任。 モジュールが変更される理由は一つであるべきです。
実装ではなく、インターフェースに対してプログラミングする。
エラーを握りつぶさない。 すべてのエラーは情報です。
創発的設計： すべてのテストを通す、重複なし、意図を表現する、複雑さを最小化する。この順序で。

コンテキストに依存するもの

これらの原則は健全ですが、具体的なルールはAI以前の時代や特定の言語の世界を反映しています。私たちは文字ではなく、精神を適用します：

DRY。 乖離する重複は危険です。しかし、繰り返しパターンをすべて抽象化すると、かえって悪い間接参照が生まれます。時として、別のファイルに時期尚早な抽象化を置くよりも、ここに3行の読みやすいコードがある方が良いのです。
厳格なTDDのセレモニー。 原則 — テスト済みのコードをリリースし、動作を確認する — は譲れません。セレモニー — コードの前にテストが存在しなければならない — は人間がゆっくりタイプするワークフロー向けに設計されたものです。テストを書きましょう。パスすることを確認しましょう。テストとコードのどちらが先かよりも、両方が存在するかどうかの方が重要です。
ボーイスカウトルール。「キャンプ場をきれいにして帰る」— はい。しかし、ボーイスカウトが片付けたのはキャンプ場であり、森全体ではありません。触れた部分を直しましょう。1行変更したからといってファイル全体の構造をリファクタリングしてはいけません。

AI時代の追加事項

原則に基づくガイダンスは、ルールよりもスケールする。 原則は判断を許容します。ルールは脆いです。
エージェントが構築したものは、エージェントが保守できるべき。 会話のコンテキストと成果物を保持しましょう。結果だけでなく、構築プロセスもドキュメント化しましょう。
巧妙さより明快さ。 このシステムを構築したものが、推論を再構成して正しく修正できる必要があります。明示的な構造は、巧妙で小さな抽象化に勝ります。
これはインフラストラクチャになり得るか？ ツールはあなたの問題を解決します。インフラストラクチャは他者がその上に構築することを可能にします。それに応じて設計しましょう。

人間が線を引くところ

AIはツールです。驚くほど優秀なツールです。しかし、AIがやらないことがあります：

プロダクトの意思決定。 どの機能を構築するか、何を削るか、アプリがどう感じるべきか。「システムTTSの品質評価は『まあまあ使える』と表記すべきだ、なぜなら本当にひどいから」— これは実際に聴いた上での人間の判断です。
テイスト。 AIはきれいな文章を書けますが、プロジェクトの声、品質について率直であるという決定、Francisco を目立つ形でクレジットする選択 — これらは人間の判断です。
倫理。 PostHog の削除はリファクタリングタスクではありませんでした。「設定ページにはテレメトリを収集しないと書いてあるが、コードにはアクティブな PostHog のAPIキーがある。これは嘘だ。修正しろ。」でした。AIは実行しました。問題を特定し、それを重要だと考えたのは人間です。
チェス。 盤面はあなたのツーリングを気にしません。

なぜこれを共有するのか

「AIで構築」が無意味になっているからです。誰もがそう言います。誰もそれを見せません。興味深い問いは、AIが関与したかどうかではなく、どのように関与したか、そして人間が実際に何を貢献したかです。

これがその答えです。人間がビジョン、テイスト、判断力、そして説明責任をもたらします。AIがベロシティ、記憶、そして午前2時に Rust のエラーメッセージを読む不屈の意欲をもたらします。

どちらか一方だけではこのプロジェクトは構築できません。両方がクレジットされます。それが約束です。

En Parlant~ は、Francisco Salgueiro による En Croissant のフォークであり、Anthropic の Claude Code を使用して構築されました。