1. はじめに

この記事は、弊社（Open Reach Tech）が OSS にした AI 開発フレームワーク『Hora Kit』の設計を解説するシリーズの 1 本目です。メイン記事はこちらです。

本当の意味での自動開発を実現するためのAI開発フレームワーク『Hora Kit』をOSSにしました

用語の確認。 Hora Kit で打つコマンドは /hora の 1 つだけです。/hora が状況に応じて /hora-spec（仕様書を書く）、/hora-setup（実装リポジトリを作る）、/hora-plan（版を確定し、機能一覧と契約を書く）、/hora-build（1 機能を 18 の関所に通す）、/hora-accept（検収する）を順に呼びます。/hora-hotfix だけは /hora が呼ばず、人が直接打ちます。docs はこのうち /hora-spec を「決める側」、残りを「作る側」と呼んでいて、この記事でもその呼び方を使います。

Hora Kit の docs には architecture.ja.md という文書があって、これが 40KB あります。弊社としては全部読んでほしいのですが、いきなり 40KB は重いと思うので、この記事ではその骨格だけを取り出して、全体像を先に頭に入れてもらうことを目的にしています。細かいところは docs か、このシリーズの他の記事に譲ります。

先に結論を言っておくと、Hora Kit は「1 つの文書を共有する 2 台の機械」です。この一文が腑に落ちれば、あとの記事はどれもこの図のどこかを拡大したものとして読めます。

2. 2 台の機械と 1 つの文書

1 台目は /hora-spec です。製品を望む人と対話しながら、何を作るかを決めて仕様書に書きます。2 台目は作る側で、/hora が /hora-setup、/hora-plan、/hora-build、/hora-accept を順に呼び、その仕様書に書かれていることを実際に作ります。docs はこの 2 台目を、オーケストレーターの名前をとって単に /hora と呼んでいます。

2 台が共有しているのは specs/<version>/spec.md という 1 つのファイルだけです。だからそれぞれを単独で説明できますし、片方だけを差し替えることもできます。

なぜこの 2 つを分けているのか、という話を少しします。1 つのエージェントに要件の整理から実装までを任せると、仕様に書いていないことが出てきたときに、エージェントが実装の都合で決めてしまいます。決めたこと自体は会話ログの奥に沈むので、あとから「なぜこうなっているのか」を追うのが難しくなります。

「何を作るか」を決める機械と「どう作るか」を実行する機械を分け、間に人が承認した文書だけを置く、というのは、この問題に対する Hora Kit の答えです。

3. 仕様は対話で、実装は自動執行で

2 台の機械は、必要とする人の注意の量が違います。

/hora-spec はステージごとに人が付き添う価値があります。最初から最後まで対話であって、ここで手を抜くと仕様書が「機能名の一覧」で終わってしまうからです。一方で /hora は走らせたまま放っておけます。答えが必要になったときには、推測で埋めずに止まって尋ねるので、自動で進めても危なくありません。

docs はこの使い分けを「仕様は対話で、実装は自動執行で」と呼んでいます。自動執行が片方では安全で、もう片方ではそうでない理由は、この「止まるかどうか」の違いだけです。

4. 4 つの層

/hora の側をもう少し分解すると、4 つの層になります。

上から下へ、「いつ」→「何を」→「どう」の順に責任が移っていきます。上の層は下の層の中身を知らず、下の層は自分がいつ呼ばれるかを知りません。この表で一番意外に思われるのは 4 行目で、Hora Kit 本体は resolver の書き方もテーブルの形も一切持っていません。その理由はシリーズ 2 本目に書きました。

3 つのエージェントの役割は次の通りです。

• hora-implementer は、1 関所ぶん、または 1 単位ぶんのコードとテストを書きます。git と .hora/ には触れません
• hora-verifier は、1 関所の終了条件が本当に満たされているかを検めます。読み取り専用で、直しません
• hora-digester は、装備されたスキル 1 つを、実装エージェントが常駐させられる大きさに要約します

そして、この 4 つの層はどれもプロジェクトのリポジトリの中にはありません。全部が npm パッケージとして届き、リポジトリが持つのは仕様書と記録だけです。

5. どの層にも属さない skill が 1 つ

/hora-hotfix だけは、上の 4 層のどこにも入りません。/hora が決して起動しない唯一の skill で、作業の順序も関所の終了条件も決めません。

なぜかというと、何を緊急とするかは人が決めることだからです。人が直接呼び、release/<version> ではなく main の上で動き、その結果の上に /hora が開いているリリースラインを rebase します。この経路の話はシリーズ 10 本目にあります。

6. 全体を支える 2 つの境界

ここまでの構造は、2 本の線の上に載っています。

1 本目は所有権の分割です。specs/ は人間のもので、.hora/ はキットが書きます。specs/ に問題があったとき、キットがやるのは尋ねることであって、直すことではありません。誤字も壊れた構成も同じ扱いです。docs には「『些細だから直しておこう』を一度でも許せば、この規則は消えます」と書いてあって、弊社もその通りだと思っています。/hora-spec と /hora-plan だけが specs/ に書けますが、どちらも人がたった今読んで承認した文言だけを書きます。

2 本目は、分類は推論してよいが内容は推論してはいけない、という線です。

この 2 本の線が守っているのは、結局 1 つのことです。人がその文言を読まないまま、要件が specs/ に入ることは決してない、という不変条件です。

7. この形が退けている 2 つのやり方

docs は、この構造を「もう一方のやり方」との対比で説明しています。

1 つ目は、specs/ を人間だけの領域にしておくやり方です。空の仕様書と書式の説明書を渡された人は、書きやすいところだけ書き、残りは /hora-plan が 1 問ずつ、いつまでも尋ねることになります。docs はこれを「誰も 2 度はやらない一歩」と呼んでいます。だから /hora-spec が書く側に回り、その代わり「AI が要件を決めた」にならない仕組みをそちらに全部寄せています。

2 つ目は、層ごとに作るやり方です。バックエンドを全部、フロントエンドを全部、最後にテスト、という順番だと、設計の不備が表に出るのは最後で、その時点で上には全部が積み上がっています。

2 台の機械に分け、機能ごとに関所を通す今の形は、この 2 つの裏返しです。

8. まとめと、次に読むもの

Hora Kit を一枚の絵にすると、人が承認した文書を真ん中に置いて、決める機械と作る機械が両側からそれを読んでいる図になります。決める側には人が付き添い、作る側は放っておける。この非対称が全体の設計を貫いています。

このシリーズの他の記事は、上の図のどこか 1 か所を拡大したものです。

• 4 つのスキルパッケージと Kit の分担: Hora Kit が手順を 1 つも持たない理由
• リポジトリの構成: 実装コードを 1 行も持たないリポジトリが全体を指揮する
• /hora の側: 1 つの機能が通る 18 の関所と 4 つのゲート
• /hora-spec の側: AI に仕様書を書かせて、AI に要件を決めさせない
• 状態と記録: 状態ファイルを持たない再入可能オーケストレーター

原典はこちらです。地図を持った状態で読むと、40KB でも意外と読めます。 https://github.com/openreachtech/hora-core/blob/main/docs/architecture.ja.md