aishell AGENTS.md

AIShell project instructions

製品目的

AIShellのnorth starは、macOSの生きた状態を直接所有し、その状態からAI開発に必要な最小情報と操作を生成して、成功課題あたりの総model tokenと所要時間を減らすこと。

優先順位:

1. correctness / task success
2. total model tokens per solved task
3. wall time / model・tool往復
4. compatibility

Direct OSは交換可能なbackendではなく、効率化を生む設計上の根である。AIShellがfile identity、OS変更の観測・照合state、process lifecycle、worktree、artifactをモデルより下で所有する。安全性は現行の許可root、停止、Trash、SHA競合検出を床として維持するが、現在の最適化対象ではない。

新機能は、OS状態を直接観測・保持して再scan、再読、再実行、model往復を減らせる場合だけ採用する。OS状態と無関係な便利toolや薄いwrapperを詰め込まない。

必要時の参照先

• 完了した能力拡張campaignの経緯が必要な時だけdocs/archive/development-efficiency-plan.mdを読む。現行の製品目的と設計境界は本ファイルを正とする。
• 外部調査の前だけrag/INDEX.mdを検索する。
• 公開挙動、配布、利用手順を変える時だけREADME.mdを読む。
• 文書の所有と寿命を判断する時だけdocs/README.mdを読む。
• legacy挙動の由来が必要な時だけdocs/archive/direct-os-spike.mdを読む。今後のGUIロードマップには使わない。

削減率は、隔離された同一model snapshot、reasoning、fixture、prompt、sandboxでbaselineと比較できる場合だけ主張する。主KPIは失敗試行のtokenも含むtokens per solved task。wire bytesやtokenizer概算をprovider報告tokenと混ぜない。

アーキテクチャ境界

• AIShellは単独でinstall、config、state/schema、migration、diagnostics、recovery、 update、releaseできる契約を本repo内に持つ。dotagentsは製品横断wireと互換projectionを 統合するだけで、AIShellの内部状態や運用判断を制御しない。
• AI hostがreasoning、thread、compaction、sub-agent、汎用PTYを所有する。AIShellで再実装しない。
• AIShellは許可root、file identity、FSEvents観測とfilesystem照合によるdelta、直接起動したprocess、完全log/artifact、freshnessを所有する。FSEvents単独を完全な履歴とは見なさない。
• Git、rg、compiler、test runner、SourceKit-LSPはAIShellが直接起動・監視するworkerとして再利用する。状態の所有者や公開toolの寄せ集めにはしない。
• shell文字列を評価せず、executable URL、引数、working directoryを分離したままprocessを起動する。shell群、env、osascriptのbasename拒否は汎用shell wrapperへ退行させない製品上の設計レールであり、security boundaryではない。許可workerの子processや改名binaryまで阻止するものとして扱わない。
• AIShellCoreへdomain機能、AIShellMCPへprotocol変換を置く。MCP handlerへ開発ロジックを埋め込まない。
• 既存20 primitiveは互換経路・下位実装としてfull profileに残す。baseline fullは高密度5＋control 2＋legacy 18の25 tool、expanded-v1 fullは高密度9＋control 2＋legacy 18の29 toolである。

Tool / result規約

• stable MCP 2025-11-25を実装基準にし、structured resultはtop-level objectとoutputSchemaを持たせる。
• schema、tool順、descriptionは決定的にする。timestamp、cwd、runtime状態をdefinitionへ混ぜない。
• 通常結果は短いsummaryとprimary evidenceだけ。完全結果はexpires_at付きhandleで保持する。
• 省略可能なread/search/run系高密度出力にbudgetを設け、omitted、has_more、cursor、freshnessを明示する。
• silent truncation、silent full-scan fallback、silent backend fallbackは禁止する。advertised retention中の一次証拠を削除しない。
• cursor失効、内容変更、index staleは機械判定可能なerrorにする。
• 新しい公開toolは、既存toolとの重複とbaseline比較を示してから追加する。