Show HN: もう一つのマークアップ言語エンジニアリングツールキット

Yamlet は、エージェントを使った仕様駆動開発のための、最小限かつ「単一情報源」を重視した仕様形式とツールキットです。基本的な考え方は、各 .yamlet.yaml ファイルに1つのコンポーネント、1つの契約、少数の要件、そしてEARS形式の受け入れ基準を書くこと。つまり、「必要な最小限を記述しつつ、最大の意味を伝える」ことを目指しています。これにより、AIエージェントが要件を誤解する余地を減らします。

プロジェクトは、macOSとLinux（Intel / Apple Silicon）向けの自己完結型バイナリ「yamlet」を提供します。Homebrew によるインストールのほか、GitHub Releases からtarballをダウンロードし、SHA256SUMSで検証してPATHに通す方法もあります。さらに、Claude Code のプラグインとしても利用でき、/plugin marketplace add と /plugin install で簡単に有効化できます。

ワークフローは主に3つの段階で構成されます。Author 段階では、yamlet-author スキルが対話形式でヒアリングし、CLI 経由で仕様を追記します。YAML とIDの生成はすべてCLIが担当するため、ファイルは構造的に常に正しくなります。Verify 段階では、yamlet verify が機械的なルールカタログを使って仕様を検証します。Project tests 段階では、yamlet tests が各受け入れ基準をGherkin の .feature ファイルに変換します。ステップ定義やコード生成は開発者に委ねられており、過度に自動化されたパイプラインは意図的に作られていません。

作者は、既存のフレームワークが冗長で信頼性に欠けると指摘します。記述量が多いほどエージェントは目標を多様に解釈しやすくなり、結果として要件の曖昧さやゴールの揺らぎが生じるからです。Yamlet はその問題に対し、仕様を「検証可能な形で小さくまとめる」ことで解決を試みます。また、MCP サーバーや多数のスキル群は不要とし、5つの Claude Code スキルを1つのプラグインにまとめています。

仕様形式の詳細を見ると、トップレベルキーとして system（slug形式）、topic、summary、description、blast_radius（low/medium/high）、front（internal/external）、空でないrequirementsリストが必須です。exposes、components、connections はオプションです。exposes はコンポーネントの契約シグネチャを定義し、名前、意図、名前付き入力、オプションの名前付き出力を持ちます。受け入れ基準は {input.NAME} や {output.NAME} で参照し、検証器が参照の解決と未使用宣言の有無を双方向にチェックします。

複合コンポーネントでは、components がメンバー仕様を alias: path の形で列挙し、connections が sink: source の形式で配線を記述します。検証はファイルをまたいで行われ、各エンドポイントをメンバーの exposes と突き合わせ、データフローの向きを非対称に解決し、すべてのメンバー入力が配線されていることを確認します。複合コンポーネント独自の requirements は省略可能で、配線では表現できない創発的な義務だけを記述します。

要件は RQ-N というIDを持ち、説明と非空の受け入れ基準リストで構成されます。各受け入れ基準（AC-N）には pattern、必須節、非空の shall リストがあります。pattern ごとの必須節は次の通りです。ubiquitous は常時、state は while、event は when、optional は where、unwanted は if、complex は while に加えて when/if のいずれか1つです。節や shall 文に {n} のようなプレースホルダーを使う場合は、examples テーブルが必須で、各行がすべてのプレースホルダーを結び付けなければなりません。

可視化機能として yamlet graph を利用すると、仕様の構造を図示できます。デフォルトの Graphviz DOT 形式で出力し、dot -Tsvg でSVGに変換できます。--format=json を指定すると、レンダラーに依存しない安定したグラフモデル（yamlet.graph/v1）を出力するため、独自のビューアやエンジンで再利用できます。複数の仕様を再帰的に展開して、合成ツリー全体を一つのJSONとして扱うことも可能です。

同梱される5つのスキルは、yamlet-author（ヒアリング支援）、yamlet-contract-challenger（契約凍結前の対抗的レビュー）、yamlet-criteria-challenger（要件コミット前の対抗的レビュー）、yamlet-verifier（ルール検証）、yamlet-tester（Gherkin ツリー再生成）です。契約は init 後に変更できず、いったんコミットした要件や基準は編集できないため、各ゲートでのレビューが最後の低コストな対策になります。メインフローは /yamlet-author で開始し、2つのゲートを経て、最後に verifier と tester が実行されます。すべての書き込みはCLIを経由するため、一貫性が保たれます。プロジェクトは MIT ライセンスで公開されています。