8 文かけて述べた規則は、毎回 8 文ぶんの費用がかかる
「Hora Kit の設計」シリーズの 11 本目。kit/ は毎回読まれ、docs/ は読まれない。8 文かけて述べた規則は、毎回 8 文ぶんの費用がかかります。Hora Kit を使わない方でも、Claude Code の skill を書いている人なら誰にでも関係する、skill の書き方の話です。
1. はじめに
この記事は、弊社（Open Reach Tech）が OSS にした AI 開発フレームワーク『Hora Kit』の設計を解説するシリーズの 11 本目です。メイン記事はこちらです。
本当の意味での自動開発を実現するための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 を使わない方にも読んでほしいと思っています。Claude Code の skill を書いている人なら誰にでも関係する話だからです。
自分の skill に「なぜこの規則があるのか」を丁寧に書いている方は、少し耳の痛い話になるかもしれません。
2. kit/ は毎回読まれ、docs/ は読まれない
Hora Kit のリポジトリには、文章が 2 種類あります。
kit/ | docs/ | |
|---|---|---|
| 誰が読むか | エージェント。実行時に、毎回 | 人。問いを持って、自分の意思で |
| 費用 | 文の数 × 実行回数 | 0 |
| 何を書くか | 規則 | 論拠、退けた代案、防いでいる失敗 |
docs の writing-style.ja.md は、この一文で始まります。hora の各パッケージが配る全ファイルは、エージェントが動く前に実行時に読まれる。8 文かけて述べた規則は、毎回 8 文ぶんの費用がかかる、と。
skill を書くとき、「なぜこの規則があるのか」を skill の中に書きたくなります。そのほうが親切に見えますし、1 か所で読めます。ところがそれは、エージェントが実行するたびに、規則 1 つにつき数段落を読み込ませることでもあります。しかも「なぜ」の部分は、規則を正しく適用するために必要ないことがほとんどです。
だから Hora Kit では分けています。「なぜ」は docs へ、「何を」は kit へ、です。
3. kit/ 側の 3 つの規則
1 つ目は、規則を述べ、失敗を物語らない、です。
✅ Match on what a description says, never on what a name sounds like.
❌ Match on what a description says, never on what a name sounds like. Two
skills whose names differ by one word can serve different surfaces
entirely, and a name that stops matching does not announce itself — the
gate simply runs without its convention and reports a pass, which is the
one kind of failure a gate must not have.
規則のあとに「破ったらどうなるか」を 2 段落続けても、規則は 1 つのままです。理由は、それがないと規則を正しく適用できない場合にだけ、1 節で残します。
2 つ目は、一度だけ書き、他は指す、です。規則ごとに所有ファイルを 1 つ決め、他のファイルは 1 行の参照だけ置きます。これは Hora Kit がスキルパッケージに対して既に採っている考え方（写しは黙って古くなる）と同じで、自分たちの散文にも同じく適用しています。
3 つ目は、1 文 1 主張です。2 つめの主張を繋ぐ em ダッシュは、そこで文を切ります。40 語が上限の目安です。
4. 行レベルでの意味
| 太字 | 命令・禁止そのものだけ。1 節あたり 1〜2 個 |
| em ダッシュ | 1 文に 1 個まで。2 個目は文の切れ目 |
| 見出し | 6 語以内の名詞句。他ファイルが引用している見出しは、引用側を直さずに変えない |
| 相互参照 | 規則 1 つにつき 1 個、文末に置く |
| 否定 | 成り立つことを書く。1 文に否定 2 つを入れない |
| 箴言 | 1 文書に 1 つまで |
description: | 2 文・40 語。何をするか、いつ動くか |
この中で特に重要なのが description: の行です。Hora Kit はスキルを名前ではなく description でマッチするので、ここが「何をするか、いつ動くか」を 2 文で言えていないと、そのスキルは呼ばれません。
5. 圧縮しないもの
完全一致で読まれるため、表現を良くすると壊れるものがあります。
checkpoints.mdの 18 チェックポイント見出し。/hora-planが逐語コピーします_plan.mdの節名:## Features,## Features — adopted as built,## Not accepted,## Withdrawn,## Acceptance- 判定の語法:
reach: full,reach: scoped,passed over <n> of <m> features; <k> not accepted,version-criteria:,not-accepted:
これらは文章ではなく識別子です。「文章を整える」つもりで触ると、他のファイルが見つけられなくなります。
6. docs/ 側の文体は、逆向き
docs 側には document-style.ja.md という別の文体規則があります。そこには、2 つを隔てているのは費用だ、と書いてあります。skill ファイルの規則は実行のたびに支払われるので、あちらの 3 つの規則はすべて圧縮についてのものになる。一方 docs は実行時に読まれないので、議論に費用がかからない、と。
だから docs では、論拠を述べること、退けた代案を示すこと、その規則が防いでいる失敗を名指すことが、すべて場所に値します。予算は長さではなく、見つけやすさです。値しないのは、読者が 4 つの節から組み立て直さなければならない主張だけです。
太字の使い方も違います。docs では「命令、禁止、あるいは流し読みする読者にも持ち帰らせたい唯一の事実」に太字を使い、段落の主題は太字にしません。それは見出しの仕事だからです。
ついでに書いておくと、docs は日本語版と英語版の対で書かれていますが、日本語版は翻訳ではありません。片方を直したら同じコミットでもう片方も直す、という規則で、両方が原典です。
7. Claude Code の skill を書く人へ
Hora Kit を使わなくても、この分け方は使えると弊社は思っています。弊社が勧めるチェックは 3 つです。
この文は、規則を正しく適用するために必要か。必要ないなら docs へ。この規則は、他の skill にも書いていないか。書いていたら片方を参照に変える。description: は 2 文で「何をするか、いつ動くか」を言えているか。言えていなければ呼ばれない。
skill は毎回読まれます。1 文減らすと、その skill が動くたびに 1 文ぶん安くなり、しかも規則の適用精度は下がりません。skill が長くなって困っている方の参考になれば幸いです。
原典はこちらです。 https://github.com/openreachtech/hora-core/blob/main/docs/writing-style.ja.mdhttps://github.com/openreachtech/hora-core/blob/main/docs/document-style.ja.md
