宣言性
属性、JSON Schema、Link、Embed、Cacheableなどで、アプリケーションの意味をコード上に宣言します。AIは隠れた規約を推測するより、宣言された意味を根拠にできます。
AI-ready architecture
AIが推測しなくていいアプリケーションへ。
AIエージェントがコードを読み、変更し、説明するなら、曖昧な規約よりも、コード上に残る意味が重要です。BEAR.Sundayは、アプリケーションの意味をリソース、属性、スキーマ、リンクとして残します。
明示性
onGet / onPost、コンストラクタ注入、DbQuery、context moduleにより、入力、依存、実行時構成が明示されます。レビュー対象が関数の中だけに閉じません。
トレーサビリティ
URI、リソース、リンク、スキーマ、ドキュメントが同じモデルに接続します。変更の影響を、実装からAPIドキュメント、llms.txtまでたどれます。
厳格な型
PHPStanとPsalmの高い静的解析レベルを前提に、単なるarrayではなくshaped array、domain array、domain typeとして意味を残します。型そのものがAIの文脈になります。
Design principles for AI
設計原則が、AIの判断材料になる。
BEAR.Sundayは、Clean Architecture、CQS/CQRS、DDDを名前として掲げるためのフレームワークではありません。 しかし、それらが重視してきた依存方向、読み書きの分離、業務語彙の境界は、AIが変更を判断する時代に そのまま強い手がかりになります。
Clean Architectureのエッセンス
依存方向はinterfaceとDI moduleで制御され、フレームワーク、DB、HTML、API、CLI、キャッシュは外側の詳細になります。AIは、何がアプリケーションの意味で、何が差し替え可能な詳細なのかを分けて読めます。
CQS / CQRSのエッセンス
読み取りと書き込みでは最適なモデルが違う、という中心だけを取り出します。SQLがprojectionを定義し、PHPが型と振る舞いを与えるread modelは破棄可能です。状態変更と不変条件はcommand/write pathの責任として分けて推論できます。
DDDのエッセンス
URI、Resource、interface、domain type、namespaceが、業務語彙と境界をコードに残します。重い儀式ではなく、ユビキタス言語と境界づけられた文脈の手がかりが、AIにも人間にも読める形になります。
Explicit contracts
契約と情報構造が、AIに読める。
Ray.MediaQueryは、SQLをオブジェクト抽象の裏に隠しません。 Interfaceが契約を示し、SQL fileがprojectionを示し、戻り値型が結果の扱いを示します。 AI assistantは、隠れたquery generationを逆算する必要がありません。 リソース間の関係も、Link、Embed、crawl、URIとして宣言されるため、情報構造を実装からたどれます。
Interfaceが契約になる
DbQuery interfaceは、アプリケーションが何を求めているかを示します。呼び出し側はSQLの組み立て方ではなく、メソッドシグネチャと戻り値型に依存できます。
SQLがprojectionになる
JOIN、CTE、window function、集約、画面固有の列を、隠れたquery generationではなくSQL fileとして明示します。AIは実際に何が実行されるかを読めます。
戻り値型が意図を示す
行リスト、1行、hydrated object、void、AffectedRows、pagination、custom wrapperなど、戻り値がfetch、hydrate、wrap、ignoreの意図を宣言します。
Read modelを小さくテストできる
SQL、factory、domain object、applicationを層ごとに確認できます。Application testではtyped return valueを持つinterfaceをfakeでき、use caseに集中できます。
Embed / crawlが情報構造を宣言する
関連するコンテンツの構造を、Link、Embed、crawl名、app:// URIで宣言します。AIはHTMLを観察して関係を推測するのではなく、実装に残ったリソースグラフをたどれます。
Tool-ready resources
リソースが、そのままAIの道具になる。
BEAR.ToolUseは、BEAR.SundayのResourceObjectからAI agent向けのTool Use定義を生成します。 URI、JSON Schema、ALPS、PHPDoc、属性で表現された意味が、AIの実行可能な道具になります。 LLMそのものには依存せず、アプリケーション側のinterfaceとしてagent loopを構成できます。
ResourceObjectからTool定義を生成する
既存のリソースクラスからJSON Schemaベースのtool definitionを生成できます。AI向けに別の関数群を作るのではなく、アプリケーションの機能そのものを道具にできます。
URIで使わせる機能を指定する
app://self/userやpage://self/searchのように、公開するリソースをURIで選べます。#[Tool]と#[Exclude]で、AIに渡す機能の範囲をコード上に残せます。
説明は実装から集める
JSON Schema、PHPDoc、ALPS profileからパラメータ説明や制約を組み立てます。AIが入力を推測するのではなく、実装に接続した説明を読めます。
破壊的操作には確認を挟む
confirm付きのtoolは、人間の承認を得てから実行できます。Streaming Agentでは確認イベントを返し、応答がなければ拒否する安全側の動作にできます。
大きな結果は絞って渡す
filterでtool resultをLLMへ渡す前に要約できます。検索結果や一覧の巨大なbodyから必要なフィールドだけを渡し、トークン効率と情報設計を保てます。
呼び出しを監査できる
ToolCallObserverで成功、エラー、例外、未知toolを含むdispatchを観察できます。監査ログ、メトリクス、レイテンシ計測をアプリケーション側の文脈で実装できます。
REST semantics as a safety model
RESTの意味論が、そのままAIの安全モデルになる。
リソースを道具にできるのは、新しい仕組みを足したからではありません。URI、統一インターフェース、 型、JSON Schema、ALPSが、最初からツール定義の形をしているからです。そしてRESTが古くから持つ 「安全」「冪等」というメソッドの意味論が、エージェントに何を自由に呼ばせ、何に確認を挟むかを 決める根拠になります。BEAR.ToolUseは、単発のツール呼び出しから、専門エージェントを編成する ランタイムへと広がっています。
安全な操作は自由に、危険な操作は確認を
GETのような安全・冪等な操作はエージェントに自由に呼ばせ、状態を変える操作にはconfirmを挟みます。RESTのメソッド分類が、そのまま道具の権限モデルになります。
ALPSが、意味をフィルタに変える
ALPSプロファイルのsafe / idempotentな遷移情報から、実行時に渡す道具を絞れます。読み取り専用モードを、思いつきではなくリソースの意味論から導けます。
エージェントは、リソースグラフを辿る
ハイパーメディアがクライアントにリンクをたどらせるのと同じ構造で、エージェントはURIとリンクをたどって調査し、操作します。リソースグラフが、そのままエージェントの地図になります。
専門エージェントへ委譲する
コーディネーターがask_criticやask_editorのように、専門エージェントを道具として呼べます。設計レビューと文章校正のように、役割の違う専門家を編成できます。
文脈を継続する
複数回の実行にわたって会話履歴を保ち、調査・レビュー・修正の多段ワークフローを、文脈を作り直さずに進められます。
実行ごとにポリシーを変える
渡す道具の一覧を実行単位で絞り、読み取り専用、コスト上限、安全方針を、エージェント本体を変えずに適用できます。
Explicit context
学習量より、明示された文脈。
AI時代には、有名なフレームワークほど有利だと言われることがあります。 しかし公開コードの多さは、そのまま正しい文脈の多さを意味しません。 異なるバージョン、異なる品質、異なる設計判断が混ざったコーパスから平均的な形を取り出すだけでは、 クリーンな変更になるとは限りません。
BEAR.SundayがAIに渡すのは、曖昧な慣習ではなく、実装に接続した明示的な文脈です。 interface、型、URI、Link、Schema、Module、生成ドキュメントが、AIの推論に必要な根拠になります。
学習量は、文脈の代わりにならない
有名なフレームワークには公開コードが多くあります。しかし、その中には異なるバージョン、設計方針、品質のコードが混在します。AIが平均的なパターンを拾うだけでは、現在のアプリケーションにとって正しい判断とは限りません。
検索できる知識から、確信できる文脈へ
Stack Overflow的な集合知は、実装の断片を探す時代には大きな価値がありました。AI時代には、外部の断片よりも、目の前のコードベースがAIに正しく推論させるだけの根拠を持っているかが重要になります。
明示性が、クリーンコードを助ける
BEAR.Sundayでは、interface、ResourceObject、Module、JSON Schema、APIドキュメント、llms-full.txtが、AIに読ませるための明示された情報設計になります。推測ではなく、実装に接続した根拠からコードを組み立てられます。
局所性が、推論コストを下げる
DIにより依存はコンストラクタとModuleへ現れ、責任はResource、Query、Interceptorへ分かれます。巨大な全体像を読ませなくても、変更対象の局所的な文脈だけで判断しやすくなります。
Agent workflow
読める単位があるから、変更を任せられる。
AIにとって難しいのは、コード量そのものではなく、意味の所在が散らばっていることです。 BEAR.Sundayでは、リソースを起点に関連情報をたどれるため、調査と変更の手順が安定します。
- 01Resource URIから対象機能を発見する
- 02onGet / onPost の入力と出力を読む
- 03PHPStan / Psalm の型とshapeを確認する
- 04DbQuery interfaceとSQL fileのprojectionを確認する
- 05Link / Embed / crawlで宣言されたリソースグラフをたどる
- 06BEAR.ToolUseで公開されたtoolと確認条件を確認する
- 07JSON Schemaで表現の契約を確認する
- 08DI moduleで実行時の差分を確認する
- 09テストとドキュメントへ変更の影響を反映する
Strict types
厳格な型が、明示性と局所性を強くする。
AIが変更するコードでは、曖昧なarrayや暗黙の構造がそのまま推測の余地になります。 BEAR.SundayではPHPStanとPsalmの高い静的解析レベルを前提に、配列もshapeやdomain typeとして意味を持たせます。 型は単なる検査ではなく、AIが読むための仕様でもあります。
/**
* @phpstan-type UserRow array{id: positive-int, name: non-empty-string}
* @psalm-type UserRow array{id: positive-int, name: non-empty-string}
*/
interface UserQuery
{
/** @return UserRow */
public function item(int $id): array;
}- bare arrayではなく、shaped arrayやdomain typeとして表現の形を明示する
- PHPStanとPsalmの高い静的解析レベルで、曖昧な値の混入を早く検出する
- interface、PHPDoc、JSON Schemaを接続し、実装、テスト、ドキュメントの語彙を揃える
- AIが補完するときも、型とshapeが入力、出力、変更範囲を狭める
LLM documentation
llms.txtは、AIの入口になる。
API Doc、OpenAPI、JSON Schema、llms-full.txtは、アプリケーションを人間だけでなく AIにも読ませるための接続点です。ドキュメントが実装の外側に孤立しないことが重要です。
#[JsonSchema(schema: 'user.json')]
#[Link(rel: 'orders', href: 'app://self/orders{?id}')]
public function onGet(int $id): static
{
$this->body = $this->userQuery->item($id);
return $this;
}Start with one resource