「この金額は円単位」「この列は古いアプリも読んでいる」「価格計算を変えたら、このテストを実行する」。コードには表れにくい決まりを、AIに毎回説明していませんか。readfirstは、ファイルごとのルール・注意点・検査コマンドをまとめ、変更前に取り出すための小さな開発ツールです。
2026年11月4日11:23 JST、v0.14.0のGitHubリリースが公開されました。今回の差分は、開発エージェントへの接続設定をまとめて行うsetupコマンドです。npmの0.14.0は同日11:25 JSTに公開されています。製品全体が今日初めて登場したという意味ではありません。
macOS・Node.js v24.22.1でreadfirst 0.14.0を実行しました。日本語ルールの表示、テストの失敗と成功、接続設定の生成を確認しています。LLMには接続しておらず、バグ削減率やトークン削減、各エージェントからの接続成功は測定していません。
何が新しい？ チームの決まりを複数のAIへ渡す準備
公式ガイドによると、setupはリポジトリ内の設定を手がかりに対象エージェントを見つけます。対象を指定することも可能です。readfirstそのものを賢いモデルに置き換える更新ではなく、同じルール表へ接続する準備を省く更新です。
npx --yes readfirst@0.14.0 setup --for cursor,codex編集部の教材では、.cursor/mcp.jsonと.codex/config.tomlに接続情報が追加され、AGENTS.mdに実行を促す指示が生成されました。Cursor側に置いた既存の別サーバー設定は残りました。同じsetupを再実行すると、対象ファイル群のハッシュは変わりませんでした。これは今回用意した設定での結果で、あらゆる設定形式の保存を保証する試験ではありません。
コメント入りJSONを置いた試験では、ファイルを変更せず、手動で追加するよう案内が出ました。終了コードは0でした。つまり「コマンドが正常終了した」だけで、全クライアントへの設定完了とは判定できません。メッセージと差分を確認する必要があります。
ルールの表示と、違反の検出は別の仕事
| 段階 | 何をするか | 今回の教材で見るもの |
|---|---|---|
| read | 対象ファイルのルールや注意点を表示 | 円を100倍してはいけない、という日本語の注意 |
| check | mapの構造・ファイルとの対応を検査 | ソースコードが間違っていても通る場合がある |
| verify | 変更ファイルに対応した検査コマンドを実行 | 価格計算の期待値を、Node.jsのテストで照合 |
ここを混同すると、「ルール表を導入したから安全」という誤解が生まれます。文章で「円を保持する」と書いただけでは、実行結果が2400円なのか24万円なのかを自動判定できません。機械的に守りたい決まりには、期待値を確認するテストが必要です。readfirstは、そのテストを変更対象と結び付ける役割を担います。
この分担は、AIのモデルを替えても意味があります。ルールの伝達は開発支援ツールへ、数値の照合はテストへ、仕様の妥当性は人のレビューへ。それぞれの責任を明確にできます。ただし、登録されていない決まりや不十分なテストまで補えるわけではありません。
小さな価格計算で、失敗と成功を確かめた
教材は架空の価格計算です。商品単価1200円と個数2を受け取り、2400を返します。税計算・値引き・丸め処理は含みません。readfirstに渡すmapとテストは編集部が用意しました。AIが業務ルールを自動発見した実験ではありません。
| 操作 | 観測した結果 |
|---|---|
| read src/price.mjs | 日本語のルール、注意点、検査コマンド、関連テストのパスを表示 |
| 戻り値を unitYen * quantity * 100 に変更してcheck | 終了コード0。ルール表の対応関係が正しくても、計算の誤りは残る |
| 同じ状態でverify --base main | 終了コード1。期待値2400に対し、実際は240000で失敗 |
| 100倍を取り除き、コメントを残して再検査 | 終了コード0。価格計算のテストが成功 |
修正後にコメントを残したのは、mainとの差分を維持するためです。完全に元へ戻すと、変更がなくなって検査対象もなくなる場合があります。「検査が実行されて成功した」と「対象がなく実行されなかった」を区別してください。
ダウンロード教材で、自分でも試す
readfirst教材ZIPには、価格計算、1本のテスト、日本語のmap、READMEが入っています。実在の顧客データやAPIキーは不要です。Node.js 20以上、Git、初回のnpm取得用インターネット接続が必要です。教材を展開したreadfirst-demoフォルダーで、次の順に実行します。
git init -b maingit add .git -c user.name="Demo" -c user.email="demo@example.invalid" commit -m "Initial demo"git switch -c trialnpx --yes readfirst@0.14.0 checknpx --yes readfirst@0.14.0 read src/price.mjs次にsrc/price.mjsをエディターで開き、returnの行を次のように変えます。これは、失敗を確かめるために意図して入れる誤りです。
return unitYen * quantity * 100;npx --yes readfirst@0.14.0 checknpx --yes readfirst@0.14.0 verify --base main続いて関数を下の内容に直し、verifyをもう一度実行します。期待結果は、テスト1件が成功して終了コード0になることです。実行結果に検査コマンドが表示されたことも確認します。
export function totalYen(unitYen, quantity) { // 円単位を保持する return unitYen * quantity;}.readfirst/map.jsonのchecksにあるrunを、実行前に確認してください。今回の教材はnode --test test/price.test.mjsだけです。知らないリポジトリのmapを、そのまま信用して実行する手順にはしないでください。
今回見つけた注意点：setupした先のバージョンは固定されない
0.14.0を明示してsetupを実行しても、生成されたCursorの接続設定は、引数が["--yes", "readfirst", "mcp"]でした。起動するreadfirstにはバージョン指定がありません。これはnpm配布版の試用結果と0.14.0の実装で確認しました。
同じ版で検証を続けたい場合は、生成後の接続設定でreadfirstをreadfirst@0.14.0へ変更します。Cursorなら次の形です。AGENTS.mdなどに生成された指示文のnpx呼び出しも、版を固定する方針なら合わせて確認します。クライアントごとの設定ファイルを変更しただけでは、接続成功を確認したことにはなりません。
{ "mcpServers": { "readfirst": { "command": "npx", "args": [ "--yes", "readfirst@0.14.0", "mcp" ] } }}開発途中のツールでは、更新を受け取る便利さと、検証した版を再現することの両方が必要です。まず版を固定し、更新内容を読んでから同じ教材を実行する、といった運用を取れます。今回の記事も、将来の最新版で同じ挙動が続くとは扱いません。
実務では、まず一つの業務ルールから始める
| 仕事の例 | mapに残す決まり | 対応させる検査の例 |
|---|---|---|
| 受発注・請求 | 金額の単位、税の扱い、端数処理 | 既知の入力と期待する請求額を比較 |
| CSV連携 | 列名と順序、空欄の意味 | 見本ファイルとの互換性を確認 |
| 既存APIの変更 | 旧クライアントが使う項目を維持 | 旧形式のリクエストとレスポンスを確認 |
| バッチ処理 | 再実行しても同じ注文を重複処理しない | 同じ入力を2回処理する試験 |
この表は導入案です。readfirstの実績として測ったものではありません。まず「変更時によく忘れる決まり」を一つだけ選び、その対象ファイルと確認用コマンドを結び付けます。長い注意書きを一度に移し替えるより、担当者が見直せる範囲で試すほうが、ルールの古さやテストの不足に気付きやすくなります。
対象ファイルを編集する前に、readfirst@0.14.0のreadでルール・注意点・検査を確認してください。
業務上の決まりは、既存仕様書やテストの根拠と結び付けて提案し、不明な決まりは推測で追加しないでください。
mapに新しい検査コマンドを追加する場合は、何を実行し、どのファイルや外部サービスへ影響するか説明してください。
変更後は対象の検査を実行し、「実行して成功」「実行して失敗」「未実行」を区別して報告してください。成功した検査が保証しない範囲も残してください。導入条件、料金、ローカルLLMとの関係
公式のpackage.jsonではNode.js 20以上、MITライセンスです。CLIにモデル呼び出しはなく、今回の教材もLLM料金なしで動きました。OS別の公式な動作保証一覧は確認できていません。編集部の実測はmacOSのみで、Windows・Linuxや他のシェルでの動作は別途確認が必要です。
ローカルLLMを使う場合も、まずreadの出力を人が読んだり、必要な内容をモデルへ渡したりする構成を考えられます。モデルの重みを変える仕組みではありません。MCP経由で使うには、モデルだけでなく、利用するアプリ側のツール接続機能が必要です。本記事ではその接続試験は行っていません。
npmパッケージの取得には外部通信が発生します。また、ローカルでルールを取り出しても、その出力をクラウドAIに渡せば、記載した情報はそのAIサービスへ送られます。「CLIがローカルで動く」ことと「開発作業全体が外部へ情報を送らない」ことは分けて判断してください。
ホスト型のreadfirst-appは別サービスです。公式ガイドの料金欄では、初回無料枠と月額19米ドルのProなどが案内されています。今回はアプリの導入、GitHubへの追加権限付与、契約を行っていません。無料のCLI教材を試すために、それらは必要ありません。
採用前に見るのは、設定できたかより「何を確認できたか」
readfirstの魅力は、チームの知識をファイル単位で引き出し、検査へつなげられることです。一方で今回の教材は、checkが通ってもバグが残り得ること、setupが正常終了しても手動作業が残ること、生成設定の版が自動では固定されないことも示しました。
導入時は、日本語ルールが表示されたか、想定したテストが実際に走ったか、意図した誤りで失敗するか、既存設定を保てたか、の順に確認すると評価しやすくなります。AIがルールを守った割合や作業時間の改善は、その後に自分たちの変更履歴で測る課題です。
確認日：2026年11月4日JST、対象版readfirst 0.14.0。発見元はShow HN。海外で広く実用評価が定まったツールとは扱っていません。AIに渡す説明の根拠を揃える考え方はChainguard manpages MCPの記事、変更後の差分確認はDiffReviewの記事も参照してください。