やってみて分かったのは、AIの出力の質は、リポジトリ側の準備でかなり変わるということでした。

同じモデルでも、リポジトリに何が置いてあるかで結果が違う。プロンプトを工夫するより、守ってほしいことをリポジトリに置くほうが効きます。

いま置いているものを書きます。

「絶対に守ること」に番号を振る​

CLAUDE.md が414行あります。その半分近くが禁止事項です。

大事なのは中身より、番号が振ってあることです。

## 絶対に守ること

### A. 今の段階で新しく加わるもの

#### A-1. card_id を安定させる。これが唯一の取り返しのつかない失敗
#### A-2. レビューログを localStorage に入れない
#### A-3. レビューログは追記専用。編集も削除もしない
#### A-4. エクスポートは version 2。既存形式との相互互換を壊さない

### B. 前の段階から引き継ぐ禁止事項（変更なし）

番号があると、コードのコメントから参照できます。

/**
 * ハラカ表示の設定を無視して、母音記号を必ず残す（CLAUDE.md A-6）。
 *
 * ⚠️ 逆方向の例外は作らない。
 */
forceHarakat?: boolean;

これがあると、数か月後の自分も、AIも、「なぜこうなっているか」を辿れます。規約の本文をコードに書き写す必要がなくなるのが大きい。

禁止の理由を、必ず一緒に書く​

やってみて一番効いたのがこれです。

「〜するな」だけ書くと、AIは別の方法で同じことをやります。禁止した行為の目的が分かっていないからです。

だから理由をセットで書きます。

A-2. レビューログを localStorage に入れない

localStorage の実効上限は多くのブラウザで 5 MB 前後。レビューログは5万件で約 5 MB に達する。数年使った利用者から順に壊れる。 しかも同期 API なので、数 MB の読み書きのたびに UI が固まる。

ここまで書いておくと、AIは「じゃあ IndexedDB ですね」と自分で言います。理由が分かっていれば、こちらが指定していないケースでも正しい側に倒れる。

規約は、できる限りテストに落とす​

文章で書いただけの規約は守られません。

たとえば「トップレベルでブラウザの API を触らない」という規約があります。Docusaurus はビルド時にサーバー側で React を実行するので、window や indexedDB をモジュールのトップレベルで触ると落ちるからです。

これは「気をつける」では守れないので、テストにしました。

src/vocab/test/ssr.test.ts   ← 規約 B-4 に対応

規約の番号とテストのファイル名を対応させておくと、規約が生きているかどうかが CI で分かります。

テストに落とせない規約は、規約として弱い。 落とせないなら、せめて検査コマンドを作る。それも無理なら、その規約は守られない前提で設計を考えます。

スコープ外を、はっきり書く​

これも効きました。

### スコープ外（勝手に着手しない）

- オンライン同期・アカウント・Firebase（次の段階。SYNC-PLAN.md は将来の資料）
- 日本語 → アラビア語の産出方向の出題

リポジトリの中に将来の計画書があると、AIは親切心で先回りします。「ついでに同期の下準備をしておきました」みたいなことが起きる。

将来の資料は「将来の資料である」と書いておく。 これだけで先回りが止まりました。

順序を指定する​

マイルストーンには順序があります。そして、その順序に理由があることがあります。

Q3（保存層とエクスポート）は Q4（復習画面）より先に完成させる。

サーバを持たない構成では、エクスポートが唯一の生命線である。画面を先に作ると、復習が習慣になった頃に履歴を失う利用者が出る。

画面から作るほうが楽しいし、AIに投げても画面のほうが早く形になります。だからこそ、順序を先に固定しておく必要がありました。

3つのエージェントで、同じスキルを共有する​

いま3系統のエージェントを使い分けています。それぞれ設定を置く場所が違います。

.claude/skills/
.agents/skills/
.junie/skills/

同じスキルを3か所にコピーすると、必ずズレます。なので実体を1か所に置いて、あとはシンボリックリンクにしました。

.agents/skills/grill-me/          ← 実体
.claude/skills/grill-me  ->  ../../.agents/skills/grill-me
.junie/skills/grill-me   ->  ../../.agents/skills/grill-me

.agents/ を実体側にしているのは、特定のツールに寄せたくないからです。ツールを乗り換えても、リンクを張り替えるだけで済みます。

skills-lock.json ─ プロンプトも依存関係である​

これがいちばん書きたかった話です。

公開されているスキル（エージェント向けの手順書）を使うことがあります。他人のリポジトリにある Markdown です。

他人のリポジトリの中身は、いつ変わるか分かりません。

コードなら誰でもそう考えるのに、プロンプトだと「まあ Markdown だし」と流してしまう。でも、それはエージェントの振る舞いを決める入力です。変われば結果が変わります。

なので、ロックファイルを置きました。

{
  "version": 1,
  "skills": {
    "grill-me": {
      "source": "mattpocock/skills",
      "sourceType": "github",
      "skillPath": "skills/productivity/grill-me/SKILL.md",
      "computedHash": "f361db4e15e6bf..."
    }
  }
}

やっていることは package-lock.json と同じです。どこから来たか、どのパスか、中身のハッシュは何か。

更新するときは、ハッシュが変わったことに気づいてから、差分を読んで、意図的に上げる。黙って変わるのを防ぐのが目的です。

プロンプトは依存関係です。 だからロックする。この発想はもっと広まっていい気がしています。

やってみて分かった限界​

正直なところも書いておきます。

規約が増えると、読まれなくなります。 414行はもう限界に近い。全部を毎回読ませるより、いま触っている領域の規約だけを見せる形にしたい、と思いつつできていません。

規約どうしの矛盾に、AIは気づきません。 段階が進んで古い規約が実質死んでいても、そのまま従おうとします。定期的に自分で読み返して消す必要があります。

「なぜ」を書けない規約は、たいてい間違っています。 理由が書けないルールは、自分がまだ理解していないだけのことが多かったです。これは AI 相手というより、自分の設計の甘さが可視化される仕組みとして機能しています。

まとめ​

• 禁止事項に番号を振る。 コードのコメントから参照できる
• 禁止の理由を必ず書く。 理由が分かれば、指定していないケースでも正しい側に倒れる
• 規約はテストに落とす。 落とせない規約は弱い
• スコープ外と順序を明示する。 先回りが止まる
• スキルの実体は1か所、あとはシンボリックリンク
• 外部のスキルはハッシュで固定する。 プロンプトも依存関係

このサイトはアラビア語の学習教材です。よかったら中身も見てみてください🙇

ライセンスです。

コードを書いている時間より、「これは派生物なのか」を考えている時間のほうが長かった週があります。しかも日本語で書かれた実例がほとんど見つからなくて、かなり心細かった。

同じところで止まる人がいると思うので、判断の過程ごと残しておきます。

何をしたかったか​

単語カードを自動で作りたかったんです。

教材に出てくる単語を拾って、原形（レンマ）を求めて、活用を展開して、訳語を付けて、間隔反復で復習できる形にする。この「原形を求める」ところに形態素解析が要ります。

アラビア語の形態素解析器で、実用になるものは多くありません。そのなかで使えそうだった辞書データが、GPL v2 でした。

「or later」が無い、という一行​

ここが最初の分かれ道でした。

多くの GPL のプロジェクトは「version 2 or (at your option) any later version」と書いています。この場合、利用者は GPLv3 を選べます。

使いたかった辞書の LICENSE は、こうなっていました。

... as published by the Free Software Foundation version 2.

「version 2.」で止まっています。

つまり GPL v2 only。GPLv3 に上げる選択肢がありません。

CC BY-SA 4.0 は助けにならなかった​

「CC BY-SA 4.0 は GPL 互換」という話を見かけて、一瞬これで抜けられるかと思いました。

抜けられません。CC BY-SA 4.0 の GPL 互換は GPLv3 に対する一方向で、GPLv2 は対象にならないからです。

GPL v2 only という条件は、思っていたよりずっと狭いところに人を追い込みます。

どこからが派生物なのか​

ここが本題です。3つ問いがありました。

1. 解析結果から作った cards.json は派生物か
2. cards.json を読み込むサイト本体は派生物か
3. 生成器のソースは「対応するソース」として公開が要るか

1 は、実質的に辞書の見出し語一覧の複製になり得ます。派生物として扱いました。

3 も明らかに要ります。GPL は「配布するなら、それを作れるソースも渡せ」という要求なので、生成器を公開しないと cards.json を配れません。

問題は 2 でした。サイト本体まで GPL に引きずられると、教材ごと全部が GPL になります。 それは避けたい。

分割の方向は、1つしか成立しなかった​

「生成器だけ公開して、あとは分ける」——最初はそう考えました。

ところが解析器は Go で書いてあって、コマンド側が internal/ 以下のパッケージに依存していました。

Go の仕様上、internal/ は他のモジュールから import できません。

つまり「生成器のコマンドだけを別モジュールに切り出す」ことが構造上できない。切り出せるのは、逆側（API サーバー）だけでした。

最終的な構成​

こうなりました。

守っている規律は3つです。

• サイト本体に cards.json をコミットしない
• npm run build は cards.json を読まない
• 実行時に、GPL のリポジトリから fetch する

サイトには出典表示を置いて、「対応するソース」へ辿れるようにしています。

分けた理由は「秘匿」ではない​

これは自分への戒めとして書いておきます。

リポジトリを分けると、コミットメッセージに「private にするため」と書きたくなります。でも実際の理由は配布物として分けることです。

GPL のリポジトリは公開されていて、そこに「対応するソース」への道筋がある。隠すために分けたのではなく、混ぜないために分けた。 ここを書き間違えると、あとから読む人（と未来の自分）が判断を誤ります。

境界を Makefile に置いた​

人間が「ここから先は混ぜない」と覚えておく方式は、いつか必ず破られます。

なので、境界をコマンドに落としました。

## vocab-source: 教材語彙を darasa-vocab-cards に書き出す
##
## これが教材と生成器の境界である。
## 決定的なので、2回実行すればバイト単位で一致する。
vocab-source:
	$(NODE) scripts/vocab-source/build.mjs

## vocab: 書き出し → 生成 → 検証 → コミット
##        生成そのものは builder が行う。cards.json はここには来ない。
vocab: vocab-source
	$(MAKE) -C $(BUILDER_REPO) build verify commit

サイト本体に残っているのは、教材の MDX から見出しを抜き出して TSV に書き出すところまでです。そこから先は別リポジトリの make に投げます。

さらに、規律が守られていることを検査するコマンドも置きました。

make vocab-source-verify   # MDX を書き換えていない / build が cards.json を読まない

チェックできない規律は、規律として弱いと思っています。

諦めたもの​

ライセンスの都合で、機能を1つ落としています。

生成の過程で単語の頻度データを使っています。「どの語を、どの順で教材に入れるか」を決めるためです。

このデータもライセンス上グレーだったので、cards.json に頻度を持ち込まないことにしました。 ビルド時に選定へ使うだけで、成果物には残さない。

その結果、「あなたはコア語彙の何％をカバーしています」という指標が出せなくなりました。 学習アプリとしてはかなり欲しい機能です。

でも、カバレッジを出すために頻度データを配布物に入れるのは、線を越えます。機能のために線を動かさないと決めました。

実行時 fetch の代償​

cards.json を別リポジトリから実行時に取ってくるので、代償もあります。

• 初回表示で外部リクエストが1回増える
• そのリポジトリが落ちるとカードが出ない
• オフラインでは使えない

正直なところ、ビルド時に取り込めたら楽でした。でもそれをすると、成果物にGPLのデータが同梱されます。取り込まないことが、そのまま境界の実装になっているので、ここは受け入れています。

まとめ​

• ライセンスは最後の一行まで読む。「or later」の有無で結論が変わります
• どこからが派生物かを、先に紙の上で決める。 コードを書き始めてからだと戻れません
• 言語仕様が分割の方向を決めることがある。 Go の internal/ がそうでした
• 境界は人の記憶ではなく、コマンドとテストに置く
• 機能のために線を動かさない

同じ場所で止まっている人の役に立てば嬉しいです。

このサイト自体はアラビア語の学習教材なので、よかったらそちらもどうぞ🙇

/blog のほうはアラビア語を学ぶ人向けなので、技術の話を混ぜると読む人がねじれてしまう。なので分けることにしました。

ここに書くこと​

darasa.jp を作る過程で、判断に迷ったところを書いていきます。

• 間隔反復をサーバーなしで回すために決めたこと
• 学習の記録をブラウザだけに持つ設計と、その代償
• アラビア語をWebで表示することの難しさ
• OSS のライセンスの都合でリポジトリを分けた話
• AI と一緒に開発するための、リポジトリ側の準備

「やってみた」ではなく、なぜそう決めたかのほうを残しておきたいと思っています。数か月後の自分が読み返して、判断の理由が分かる状態にしておきたいので。

このサイトについて​

アラビア語（フスハー）を日本語で学べる学習サイトです。文字の読み方から上級文法まで87課、練習問題が1,122問。完全無料で、アカウント登録もありません。

技術構成はだいたいこんなところです。

• Docusaurus 3（MDX に演習コンポーネントを埋めている）
• TypeScript
• 学習の進捗はブラウザに保存（サーバーもDBも持っていない）
• 単語の間隔反復は FSRS-6 を IndexedDB の上で回している

詳しくはコース紹介を見てください。

書く順番​

しばらくは週1本のつもりです。最初はライセンスの話と、AI との開発体制の話から書きます。

この2つが、作っていていちばん「他の人はどうしてるんだろう」と思った部分だったので。