Show HN: AIエージェントがアーキテクチャを破壊できないTypeScriptリポジトリ

Hacker Newsで「Open Agent-Ready TypeScript」という新しいオープンソースプロジェクトが注目を集めています。これは、AI支援コーディングによく見られるアーキテクチャの劣化問題を解決することを目的としています。開発者のlucasgodt氏によるこのプロジェクトの核となる考え方は、「すべての重要なルールは、エージェントが反論できないツールによって強制されなければならない」というものです。

このリポジトリは、小規模ながら実際の請求書API（下書き→送信→支払いのフロー、金額は整数セント、適切なステートマシン）で構成され、この考え方を実証しています。文書や規約に依存するのではなく、5つの主要なガードレールを通じてAIエージェントがアーキテクチャを破壊するのを防ぎます：

1. 依存関係ルール：dependency-cruiserを使用して、違反したインポートがビルド失敗につながるようにします。src/domainは何もインポートせず（Node組み込みモジュールも不可）、エージェントはアーキテクチャを覚える必要がなく、違反コードはマージできません。

1. ミューテーションテスト：Strykerによるミューテーションテストで、テストがコード変更を検出できることを確認します。CIはミューテーションスコア75%以上を要求し、アプリケーション層は現在100%です。

1. テストと仕様の保護：Claude CodeのPreToolUseフックを使用して、エージェントがテストと仕様ファイルを編集するのをブロックします（人間が明示的に許可した場合を除く）。これにより、「テストを通す」ことがテストの削除で達成されるのを防ぎます。

1. コミットゲート：各gitコミットで完全な検証スイート（型チェック、lint、依存関係チェック、テスト）を実行し、失敗をエージェントにフィードバックします。これにより、単なる壁ではなくフィードバックループが形成されます。

1. 仕様駆動開発：各ユースケースにGiven/When/Then形式のマークダウン仕様があり、テストはそれに一対一で対応します。npm run specs（検証フローに含まれる）は、仕様のないユースケース、孤立した仕様、対応テストのない基準がないかをチェックします。

これらのガードレールに加えて、リポジトリはエージェントに優しい構造を提供しています。ルートのAGENTS.mdファイル（オープンスタンダードに従い、300行未満で正確なコマンドを含む）と、各レイヤー（domain、application、infrastructure）のローカルAGENTS.mdファイルがあります。CLAUDE.mdは1行でAGENTS.mdを指すだけなので、ツール間での移植が容易です。docs/adr/には決定の理由が記録されており、エージェントが再議論するのを防ぎます。

リポジトリにはベンチマーク演習も含まれています。AGENTS.mdの最後に、自己完結型のタスク（請求書のキャンセル）が記載されており、エージェントは仕様→テスト→ドメイン→ユースケース→HTTPのフローに従い、検証をグリーンに保つ必要があります。これにより、エージェントがリポジトリ内で正しく動作できるかどうかをテストできます。

このプロジェクトはテンプレートとしても機能し、Claude Codeスキルが付属しています。このスキルはガードレールシステム（設定、フック、CI、レイヤー構造）を保持し、請求書の例を削除して、新しいドメインを仕様優先で構築します。スキルは3つのプロジェクトタイプをサポートしています：バックエンドAPI/サービス、フロントエンドアプリ（React/Vite）、モノレポ（pnpm workspaces）。

テスト保護フックは現在Claude Codeに固有ですが、CIでのミューテーションテストはツールに依存しない最終的な保証です。JSONファイルの永続化レイヤーは意図的にシンプルで並行処理に対応していませんが、これはアダプタパターンのデモンストレーションです。全体として、このプロジェクトはAI支援コーディングにおける体系的なアーキテクチャ保護ソリューションを提供しており、注目に値します。