TypeScript CLI アプリケーション仕様ジェネレータ

このスキルは、TypeScript で分散可能な Node.js CLI アプリケーションを構築するための包括的な仕様書 (Markdown) を生成します。仕様書は、完全に機能し、パッケージ可能な CLI ツールを生成するために開発者またはコーディング エージェントが従うべきブループリントとなります。

仕様書は「コードを生成しません」。package.json 設定からコマンド アクション ハンドラーからバイナリ パッケージングまで、アプリケーションのすべてのレイヤーを説明する詳細で意見的な技術文書を生成し、実装が機械的な演習となるようにします。

テクノロジー スタック

コア スタック (常に含まれる)

これらは仕様が対象とする固定バージョンです。ユーザーが異なるバージョンを明示的に要求しない限り、変更しないでください。

コンポーネント	バージョン
Node.js	22.x LTS
TypeScript	5.x
Commander.js	12.x
tsup	8.x
Zod	3.x
Chalk	5.x
Ora	8.x

注: Chalk 5.x と Ora 8.x は ESM のみのパッケージです。プロジェクトは package.json で "type": "module" を使用し、tsup から ESM 出力をターゲットにしています。 すべてのインポートは、TypeScript ソース ファイルであっても .js 拡張子サフィックスを使用します。

オプション統合バージョン

対応する統合が選択された場合にのみ、バージョン テーブルに含めます。

コンポーネント	バージョン	選択時の条件
@inquirer/prompts	7.x	Prompts = yes
conf	13.x	User Config = yes
cosmiconfig	9.x	Project Config = yes
better-sqlite3	11.x	Local Database = yes
drizzle-orm	0.36.x	Local Database = yes
env-paths	3.x	Local Database = yes
drizzle-kit	0.28.x	Local Database = yes (dev)
execa	9.x	Shell Execution = yes
got	14.x	HTTP Client = yes
update-notifier	7.x	Auto-update = yes
@yao-pkg/pkg	5.x	Binary Packaging = yes
cli-table3	0.6.x	Table Output = yes
boxen	8.x	Banner/Box UI = yes
glob	11.x	File Operations = yes

非同期パターン (ポーリング、インライン バッチ、バックグラウンド デーモン) は追加の npm パッケージを使用しません — Node.js の組み込み機能 (setTimeout、process.kill、child_process.spawn) とコア スタックに既にあるパッケージ (進捗表示用の ora、出力用の chalk) を使用して完全に実装されます。非同期パターン タイプは PRD.md の NFR とユーザー ストーリーから検出されます。新しい依存関係バージョン行は必要ありません。

コア依存関係 (package.json)

仕様には、dependencies 設定セクションに常に以下を含める必要があります:

• commander — CLI 引数解析とコマンド ルーティング
• chalk — ターミナル カラー出力 (ESM のみ、v5+)
• ora — スピナー/進捗インジケータ
• zod — 設定、引数、API ペイロードのスキーマ検証

常に devDependencies に含まれるもの:

• typescript — TypeScript コンパイラ
• tsup — TypeScript バンドラー (esbuild ベース、ESM を処理、シェバング注入)
• vitest — ユニット テストおよび統合テスト
• @types/node — Node.js 型宣言
• tsx — スクリプトおよび開発用の TypeScript 実行
• eslint + @typescript-eslint/eslint-plugin — リント

条件付き依存関係

Prompts = yes の場合:

• @inquirer/prompts — モダン インタラクティブ プロンプト (公式にサポートされている Inquirer v9+)

User Config = yes の場合:

• conf — OS 設定ディレクトリに保存される永続的なユーザーレベル設定

Project Config = yes の場合:

• cosmiconfig — プロジェクトレベルの設定ファイル読み込み (.json、.yaml、.js、package.json をサポート)

Local Database = yes の場合:

• better-sqlite3 — 同期 SQLite ドライバー (CLI コンテキストで非同期複雑性なし)
• drizzle-orm — TypeScript ファースト ORM、スキーマアズコードとタイプセーフなクエリ ビルダー
• env-paths — OS 固有のデータ ディレクトリ解決 (macOS / Linux / Windows)
• @types/better-sqlite3 — TypeScript 型宣言 (devDependency)
• drizzle-kit — マイグレーション ジェネレータと Drizzle Studio (devDependency)

Shell Execution = yes の場合:

• execa — 改良された人間工学設計と ESM サポートを備えた子プロセス実行

HTTP Client = yes の場合:

• got — TypeScript ファースト設計の HTTP クライアント (ESM のみ、v14+)

Auto-update = yes の場合:

• update-notifier — npm レジストリに対する非ブロッキング更新チェック

Binary Packaging = yes の場合 (devDependency):

• @yao-pkg/pkg — Node.js アプリケーションをスタンドアロン実行ファイルにコンパイル

Table Output = yes の場合:

• cli-table3 — 枠線と配置を備えたタビュラー ターミナル出力

Banner/Box UI = yes の場合:

• boxen — 枠線付きターミナル ボックス出力 (ESM のみ)

File Operations = yes の場合:

• glob — ESM サポート付きファイル システム グロビング

スキルがトリガーされるとき

ユーザーが CLAUDE.md で定義されたカスタム アプリケーションに対応する アプリケーション名 と バージョン を提供したときに、仕様を生成します。スキルはプロジェクトのコンテキスト ファイルからすべての必須入力を読み込みます — コア入力の対話的な Q&A は必要ありません。

ユーザーは対象アプリケーションとバージョンを指定することでこのスキルを呼び出します。例えば:

• /specgen-ts-cli my_tool v0.1.0
• /specgen-ts-cli my_tool v0.1.0 command:deploy
• /specgen-ts-cli "My Tool" v0.1.0

スキルはマッチングするコンテキスト フォルダを特定し、すべての入力ファイルを自動的に読み込みます。

バージョン ゲート

作業を開始する前に、まず アプリケーション フォルダを解決します (下記の「入力解決」を参照)。その後、アプリケーション フォルダの CHANGELOG.md (<app_folder>/CHANGELOG.md) をチェックします:

1. <app_folder>/CHANGELOG.md が存在しない場合、このチェックをスキップします (このアプリケーションの初回実行)。
2. <app_folder>/CHANGELOG.md が存在する場合、すべての ## vX.Y.Z 見出しをスキャンし、セマンティック バージョニング比較を使用して 最高バージョン を判定します。
3. リクエストされたバージョンを最高バージョンと比較します:
   • リクエストされたバージョン >= 最高バージョン: 通常通り進行します。
   • リクエストされたバージョン < 最高バージョン: 直ちに停止。"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected." を出力してください。作業は進めないでください。

入力解決

このスキルは標準化された入力解決を使用します。次を提供します:

引数	必須	例	説明
<application>	はい	my_tool	コンテキスト フォルダを特定するアプリケーション名
<version>	はい	v0.1.0	処理をスコープするバージョン
command:<name>	いいえ	command:deploy	生成を単一コマンド仕様に制限する

アプリケーション フォルダ解決

アプリケーション名はルート レベルのアプリケーション フォルダと照合されます:

1. フォルダ名から先頭の <number>_ プレフィックスを削除します (例: 1_my_tool → my_tool)
2. 提供されたアプリケーション名と大文字小文字を区別しないで照合します
3. snake_case、kebab-case、または title-case 入力を受け入れます (すべて同じフォルダと照合)
4. 一致するものが見つからない場合、利用可能なアプリケーションをリストして停止します

自動解決パス

ファイル	解決パス
PRD.md	<app_folder>/context/PRD.md
コマンド モデル	<app_folder>/context/model/
出力	<app_folder>/context/specification/

バージョン フィルタリング

バージョンが提供された場合、提供されたバージョン以下のバージョンからのみユーザー ストーリー、NFR、および制約を含めます。例えば、v0.3.0 が指定された場合:

• [v0.1.0]、[v0.2.0]、[v0.3.0] タグ付きアイテムを含める
• [v0.4.0] 以降のタグ付きアイテムを除外
• バージョン比較はセマンティック バージョニング順序を使用します

コマンド フィルタリング

command:<name> が提供された場合:

• その特定のコマンドの SPEC.md のみを生成
• 他の既存のコマンド仕様ファイルは変更されないままです
• SPECIFICATION.md (ルート) は部分更新を取得 — そのコマンドの TOC エントリのみが追加または更新されます。他のすべてのエントリは現状のまま保持されます

入力の収集

仕様書は、プロジェクトのコンテキスト ファイルから読み込まれる 4 つの入力ソース によって駆動されます。 スキルはユーザーにプロンプト、設定、パッケージング、その他の選択肢を要求しません — これらを文脈から 自動的に決定します。

入力 1: アプリケーション名 (CLAUDE.md から)

CLAUDE.md (既にコンテキストに読み込まれている) から、カスタム アプリケーション セクションの対象アプリケーションを特定します。次を抽出します:

• アプリケーション名: セクション見出し (例: "My Tool"、"Deploy CLI")
• バイナリ名: kebab-case の実行可能ファイル名 (例: my-tool、deploy)
• アプリケーション説明: 見出しの下の説明段落
• ターゲット オーディエンス: "Used by" または "Consumers" リスト
• 依存関係: "Depends on" リスト — オプション コンポーネント決定の主なソース

アプリケーション名は以下を導き出すために使用されます:

• パッケージ名: アプリケーション名の kebab-case、スコープ付きの場合は @scope/ プレフィックス
• バイナリ名: package.json の bin エントリ
• メイン TypeScript 名前空間: PascalCase (例: MyTool)

入力 2: ユーザー ストーリー (PRD.md から)

<app_folder>/context/PRD.md を読みます。このファイルはコマンドごとに編成されたすべてのユーザー ストーリーを含みます。次を抽出します:

• コマンド: 各 ## Command: <name> または ### <CommandName> セクション
• コマンドごとのユーザー ストーリー: [USCLI00101] As a user, I want to... のようなタグ付きアイテム これらはコマンドのアクション ハンドラーとプロンプトの機能要件を定義します

ユーザー ストーリーは直接以下に情報を提供します:

• 各コマンドが公開する引数とオプション
• 表示されるインタラクティブ プロンプト (存在する場合)
• コマンドが生成する出力 (テーブル、JSON、プレーン テキスト)
• 呼び出されるサービス メソッド

重要: 打ち消し線付きアイテム (~~text~~) は廃止されています。これらを追跡可能性テーブルの「削除 / 置換」サブセクションにリストします。バージョン タグを生成された仕様の追跡可能性セクションに引き継ぎます。

入力 3: 非機能要件 (PRD.md から)

同じ PRD.md 内で、各コマンドには ### Non Functional Requirement セクションがあり、[NFRCLI0120] のようなタグ付きアイテムが含まれています。これらは以下を通知します:

• 出力フォーマット要件 (JSON、テーブル、プレーン テキスト、--output フラグ)
• パフォーマンス制約 (タイムアウト、キャッシング)
• セキュリティ要件 (認証情報ストレージ、トークン処理)
• プラットフォーム制約 (Windows 互換性、PATH 要件)

入力 4: コマンド モデル (model/ フォルダから)

最初に <app_folder>/context/model/MODEL.md を読み、次に各コマンド サブフォルダの個別コマンド モデル ファイルを読みます。

MODEL.md は以下を提供します:

• 引数/オプション数を含むすべてのコマンドのサマリー テーブル
• 各コマンドの詳細モデル ファイルへのリンク

コマンド単位のファイル (例: model/deploy/model.md):

• 型と説明を含むすべての引数定義
• フラグ、型、デフォルト値を使用したオプション定義
• このコマンドによって読み書きされるコンフィグ キー
• 呼び出される外部サービスまたは API

コマンド モデルは直接以下にマップします:

• Commander.js での Command 引数およびオプション宣言
• 設定検証用の Zod スキーマ
• サービス インターフェース メソッド シグネチャ
• --help テキスト コンテンツ

PRD.md 拡張セクション

オプション コンポーネントを決定する前に、次の拡張セクションについて PRD.md をチェックします:

アーキテクチャ原則の抽出

PRD.md に # Architecture Principle セクションが含まれている場合、CLI 決定に影響するパターンを抽出します:

抽出するパターン	仕様にどう影響するか
"コンテナベースのデプロイメント"	Dockerfile セクションを含める; 設定ファイルよりも環境変数を優先
"イベント駆動"	CLI は Webhook リスナーまたはポーリング パターンが必要な場合がある
非同期パターン (ポーリング、バッチ、デーモン)	コマンド ハンドラーの非同期戦略に通知

セクションが存在しない場合、既存の検出で進めます。

高レベル プロセス フローの抽出

PRD.md に # High Level Process Flow セクションが含まれている場合:

1. CLI が開始した操作を説明するプロセス フローは、コマンド アクション ハンドラー シーケンスに通知
2. 各フロー ステップはスピナー/進捗更新を発行できます
3. エラー処理チェーンはフローのエラー パスに従う

セクションが存在しない場合、ユーザー ストーリーからのみコマンド フローを導き出します (既存の動作)。

---

オプション コンポーネントの決定

ユーザーに尋ねる代わりに、スキルは CLAUDE.md の依存関係と要件を分析し、PRD.md と相互参照することでオプション コンポーネントを決定します。

プロンプト検出

コンテンツ パターン	プロンプト選択
NFR が「インタラクティブ」「ユーザーに質問」「プロンプト」「ウィザード」と言及	Prompts = yes
ユーザー ストーリーが --interactive モードまたはガイド付きセットアップを説明	Prompts = yes
ユーザー ストーリーが init、setup、configure コマンドを説明	Prompts = yes
すべての入力は非インタラクティブ フラグ	Prompts = no

ユーザー設定検出

コンテンツ パターン	ユーザー設定選択
NFR が「記憶」「設定の保存」「ユーザー設定」「永続化」と言及	User Config = yes
config set、config get、login、logout のようなコマンドが存在	User Config = yes
NFR が「API キー」「トークン ストレージ」「認証情報」と言及	User Config = yes
永続状態が必要ない	User Config = no

プロジェクト設定検出

コンテンツ パターン	プロジェクト設定選択
NFR が「プロジェクト設定」「ワークスペース設定」「プロジェクトごと」と言及	Project Config = yes
.mytoolrc、mytool.config.js、または package.json#mytool のような設定ファイルが参照される	Project Config = yes
ツールはプロジェクト/ワークスペース レベルで動作	Project Config = yes
ツールは純粋にグローバル/ユーザースコープ	Project Config = no

ローカル データベース検出

コンテンツ パターン	ローカル データベース選択
NFR が「実行履歴」「実行ログ」「監査証跡」「アクティビティ ログ」と言及	Local Database = yes
NFR が「キャッシュ」「ローカル キャッシュ」「オフライン」「同期状態」「最後の同期」と言及	Local Database = yes
ユーザー ストーリーが history、log、list runs、show recent コマンドを説明	Local Database = yes
ユーザー ストーリーが複数の同じ型のエンティティのローカル追跡を説明	Local Database = yes
NFR が「X 日間保持」「自動削除」「保持ポリシー」と言及	Local Database = yes
データは単純なリストを超えたフィルタリング、ソート、または集約を必要とする	Local Database = yes
すべての永続データはシンプルなキーバリュー ペアに適合する (代わりに conf を使用)	Local Database = no

ローカル データベース vs conf: データに複数の行があり、時間とともに増加し、クエリが必要な場合、または関係を含む場合は SQLite を使用します。ハンドル ユーザー設定またはシングル トークンの場合は conf を使用します。

シェル実行検出

コンテンツ パターン	シェル実行選択
NFR が「コマンド実行」「実行」「スポーン」「シェル」「サブプロセス」と言及	Shell Execution = yes
コマンドが他の CLI ツール (git、docker、npm など) を調整	Shell Execution = yes
外部バイナリを呼び出すビルド/デプロイ コマンド	Shell Execution = yes

HTTP クライアント検出

コンテンツ パターン	HTTP クライアント選択
CLAUDE.md「Depends on」が REST API または Web サービスを参照	HTTP Client = yes
NFR が「API 呼び出し」「webhook」「REST」「HTTP」「フェッチ」と言及	HTTP Client = yes
コマンドがクラウド プロバイダー、レジストリ、またはダッシュボードと相互作用	HTTP Client = yes

自動更新検出

コンテンツ パターン	自動更新選択
NFR が「更新の通知」「新しいバージョンのチェック」「自動更新」と言及	Auto-update = yes
アプリケーションは npm または GitHub リリース経由で配布	Auto-update = yes (デフォルト)
制御された環境でのみ使用される内部ツール	Auto-update = no

バイナリ パッケージング検出

コンテンツ パターン	バイナリ パッケージング選択
CLAUDE.md が「スタンドアロン バイナリ」「Node.js 不要」「自己完結型」と言及	Binary Packaging = yes
ターゲット ユーザーは Node.js がインストールされていない可能性が高い	Binary Packaging = yes
GitHub リリース、Homebrew、または Chocolatey 経由の配布が言及	Binary Packaging = yes
npm の開発者ツールチェーン使用のために公開	Binary Packaging = no (npm 配布のみ)

非同期パターン検出

3 つのサブタイプが独立して検出されます。単一のアプリケーションは 2 つ以上を使用できます。

ポーリング検出

コンテンツ パターン	ポーリング選択
ユーザー ストーリーが --watch、--follow、--wait、--poll フラグを説明	Polling = yes
NFR が「完了まで待機」「進捗をフォロー」「状態をテール」と言及	Polling = yes
コマンドが終端状態 (成功/失敗) を持つ非同期操作をトリガー	Polling = yes
すべての操作は API 呼び出し内で同期的に完了	Polling = no

インライン バッチ検出

コンテンツ パターン	インライン バッチ選択
ユーザー ストーリーが「すべてのレコード」「すべてのアイテム」「一括インポート/エクスポート」を説明	Inline Batch = yes
NFR が --concurrency、並列処理、レート制限と言及	Inline Batch = yes
コマンドが潜在的に大きなコレクション (ファイル、API リソース、DB 行) を反復処理	Inline Batch = yes
NFR が「エラーをスキップ」「失敗時に続行」「最初のエラーで中止」と言及	Inline Batch = yes
NFR が「再開」「チェックポイント」「既に処理されたスキップ」と言及	Inline Batch = yes (+ ローカル データベース)
処理は常に単一アイテム	Inline Batch = no

バックグラウンド デーモン検出

コンテンツ パターン	バックグラウンド デーモン選択
ユーザー ストーリーが daemon start、daemon stop、daemon status コマンドを説明	Background Daemon = yes
NFR が「バックグラウンド プロセス」「永続的なウォッチャー」「常時稼働エージェント」と言及	Background Daemon = yes
ユーザー ストーリーが worker または watcher サブコマンド グループを説明	Background Daemon = yes
NFR が「デタッチ」「バックグラウンドで実行」「PID ファイル」と言及	Background Daemon = yes
すべての操作は単一コマンド呼び出し内で完了	Background Daemon = no

非同期パターン vs ユーザー設定: バックグラウンド デーモンを持つアプリケーションは User Config = yes も必要とします (PID を保存するため)。スキルはバックグラウンド デーモンが検出されたときこの依存関係を自動的に強制する必要があります。

テーブル出力検出

コンテンツ パターン	テーブル出力選択
コマンドがリスト出力 (リソース、レコード、結果) を生成	Table Output = yes
NFR が「表形式」「リスト ビュー」「列」と言及	Table Output = yes

決定概要

すべての入力を分析した後、仕様書を生成する前に決定概要を生成します:

オプション コンポーネント決定:
- Prompts:              yes (PRD.md から → init コマンドには対話型ウィザード)
- User Config:          yes (PRD.md から → login コマンドが API トークンを保存)
- Project Config:       yes (PRD.md から → プロジェクトごとの .mytoolrc サポート)
- Local Database:       yes (PRD.md から → history コマンドが過去の実行をリスト)
- Async - Polling:      yes (PRD.md から → deploy --watch フラグ)
- Async - Inline Batch: yes (PRD.md から → sync --all が 1000 のアイテムを処理)
- Async - Daemon:       no
- Shell Execution:      no
- HTTP Client:          yes (CLAUDE.md から → My API に依存)
- Auto-update:          yes (npm 配布ツールのデフォルト)
- Binary Packaging:     no (npm 配布のみ)
- Table Output:         yes (PRD.md から → list コマンドが表形式出力を生成)
- Banner/Box UI:        no
- File Operations:      no

ユーザーが任意の決定に同意しない場合、進める前にそれをオーバーライドすることを許可します。

仕様書の生成

入力が収集されたあと、オプション コンポーネントが決定されたら、コマンドごとに分割された複数ファイルの出力として仕様書を生成します。仕様テンプレートを references/spec-template.md で読んで、各セクションの正確な構造とコンテンツを確認してください。 テンプレートが権威的なガイド — 密接に従ってください。

仕様書は 2 つのカテゴリに分かれています:

1. ルート SPECIFICATION.md — 共有インフラストラクチャ: package.json、TypeScript 設定、 ビルド ツール、CLI エントリ ポイント、共有サービス、UI ユーティリティ、設定管理、 エラー処理、テスト戦略、およびパッケージング。
2. コマンドごとの <command-name>/SPEC.md — 各コマンドは引数/オプション定義、サービス メソッド、 プロンプト フロー、および出力フォーマットをカバーする自己完結型仕様を取得します。

重要: 生成された仕様はコンテキスト ファイルから 実際のアプリケーション データ を使用する必要があります:

• コマンド は PRD.md からの実際のコマンド名を使用する必要があります (例: init、deploy、status)
• 引数およびオプション は model/<command>/model.md の実際の定義と一致する必要があります
• サービス メソッド は実際のユーザー ストーリーにマップされます
• 設定キー はモデルが定義するものと一致する必要があります
• バージョン タグ はすべてのユーザー ストーリー ID、NFR ID、制約 ID に付加
• 削除 / 置換アイテム は廃止されたアイテムについてリストされます

出力構造

<app_folder>/context/specification/
├── SPECIFICATION.md              ← 共有インフラストラクチャ + TOC
├── init/
│   └── SPEC.md                   ← 'init' 用コマンド ブループリント
├── deploy/
│   └── SPEC.md                   ← 'deploy' 用コマンド ブループリント
├── config/
│   └── SPEC.md                   ← 'config' 用コマンド ブループリント
└── ...                           ← PRD.md からのコマンドごとに 1 つのフォルダ

SPECIFICATION.md (ルート) に含まれるもの

1. プロジェクト概要

アプリケーション メタデータ、説明、テック スタック サマリー、バイナリ名、ターゲット プラットフォーム、 完全なコマンド リスト、および配布戦略。

2. package.json 設定

"type": "module"、bin エントリ、files、engines、 すべてのランタイム依存関係 (コア + 選択した条件付き)、すべての devDependencies、および scripts を含む完全な package.json (dev、build、typecheck、test、lint、および バイナリ パッケージング = yes の場合はプラットフォーム固有の pkg スクリプト)。

3. TypeScript およびビルド設定

ESM をターゲットにした完全な tsconfig.json。完全な tsup.config.ts、シェバング注入、 ESM フォーマット、および本番環境用の条件付き sourcemap/minify を含みます。ESLint 設定。

3a. アプリケーション バージョン設定

package.json の version フィールドは、スキル呼び出し中に提供されたバージョン引数から導き出されたバージョン値に設定される必要があります (例: 1.0.3)。複数のバージョンが提供された場合、最高のバージョンを使用します。

Commander.js は package.json バージョンを --version 出力に自動的に使用します。CLI エントリ ポイント (src/cli.ts) は Commander プログラム インスタンスで .version(packageJson.version) を呼び出す必要があります <tool> --version が正しいバージョンを出力するようにします。

バージョンは --json フラグが使用されるときの JSON 出力にも含める必要があります (例: {"version": "1.0.3", "data": {...}})。

3b. SECRET.md からの .env ファイル生成

プロジェクト ルートから SECRET.md を読んで、プロジェクト ルートに .env ファイルを生成します。 .env ファイルは SECRET.md の認証情報とプラットフォーム値を、CLI アプリケーションで使用される環境変数名にマップします。 仕様は SECRET.md からの実際の値を含む完全な .env コンテンツを定義する必要があります。

プロセス:

1. プロジェクト ルートから SECRET.md を読む
2. # Credential セクション (API ホスト、ポート、トークン) と # Platform セクション (Node.js パス など) から関連する値を抽出
3. 各値を CLI で使用される対応する環境変数名にマップ
4. KEY=value ペアを使用して .env ファイルを生成

例 .env 出力 (SECRET.md から導き出された):

# API
API_BASE_URL=http://localhost:8080/api/v1
API_KEY=

# Platform
NODE_HOME=C:\nvm4w\nodejs

ルール:

• アプリケーション (process.env 経由) で実際に使用される変数のみを含める
• SECRET.md からの実際の値を使用します — プレースホルダーまたは TODO を使用しないでください
• SECRET.md が存在しないか、値が見つからない場合は、ローカル開発の合理的なデフォルトを使用します (例: localhost、デフォルト ポート)
• .env ファイルは dotenv を使用して読み込まれます (まだ存在しない場合は依存関係として追加)
• .env ファイルは gitignored

4. アプリケーション エントリ ポイント

src/cli.ts — Commander.js Program セットアップ: 名前、説明、バージョン、グローバル オプション (--verbose、--json、--no-color)、コマンド登録インポート、および program.parse()。 ルート プログラム セットアップ、グローバル オプション伝播パターン、および非同期エラー処理パターンについて references/command-patterns.md を参照してください。

5. プロジェクト ディレクトリ構造

すべてのファイルと、コンテキストからの実際のコマンドとサービスにちなんで名付けられたすべてのファイルを使用した完全な src/ ディレクトリ ツリー。

6. 共有型

src/types/index.ts — コマンドおよびサービス全体で使用されるすべての共有 TypeScript インターフェイスとタイプ エイリアス。

7. ターミナル UI ユーティリティ

• src/ui/logger.ts — info、success、warn、error を持つ chalk ベースのロガー、 debug (--verbose でゲート) メソッド
• src/ui/spinner.ts — 型付きの start/succeed/fail/stop ヘルパーを持つ ora ラッパー
• src/ui/table.ts — cli-table3 ラッパー (表出力 = yes に条件付き)
• src/ui/output.ts — --json フラグを尊重する統合出力ハンドラー

8. エラー処理

src/errors.ts — 出力コード マッピングを備えた基本 CliError クラス。handleError() 関数 すべてのコマンド action ハンドラーで使用される、キャッチ、フォーマット、きれいに終了。

9. ユーザー設定管理 (条件付き — ユーザー設定 = yes の場合のみ含める)

src/config/user.config.ts — conf セットアップ、スキーマ (Zod)、型付きアクセッサー、および 移行戦略。キー名、デフォルト値、および OS ストレージ パス。 references/config-patterns.md を参照してください。

10. プロジェクト設定管理 (条件付き — プロジェクト設定 = yes の場合のみ含める)

src/config/project.config.ts — Zod 検証付き cosmiconfig ローダー。設定ファイル 検索パス、サポートされている形式、およびデフォルトとのマージ戦略。 references/config-patterns.md を参照してください。

11. HTTP クライアント セットアップ (条件付き — HTTP クライアント = yes の場合のみ含める)

src/services/http.client.ts — ベース URL、認証ヘッダー注入、 再試行設定、および型付きエラー処理を備えた got インスタンス。

12. シェル実行ユーティリティ (条件付き — シェル実行 = yes の場合のみ含める)

src/utils/shell.ts — ログ、タイムアウト、およびエラー処理を備えた execa ラッパー。

13. 自動更新通知機 (条件付き — 自動更新 = yes の場合のみ含める)

src/utils/updater.ts — CLI スタートアップで 1 回呼び出される update-notifier 統合、非ブロッキング非同期チェック。

14. テスト戦略

Vitest 設定、process.argv モッキングを使用したコマンド テスト パターン、サービス ユニット テスト、一時ディレクトリを使用した設定テスト。 references/testing-patterns.md を参照してください。

15. パッケージング および配布 (条件付き — バイナリ パッケージング = yes の場合のみ含める)

tsup ビルド パイプライン、@yao-pkg/pkg 設定、プラットフォーム ターゲット、各プラットフォーム バイナリの npm スクリプト、GitHub Actions リリース ワークフロー スタブ。 references/packaging-patterns.md を参照してください。

npm のみの配布の場合: package.json files、bin、engines、prepublishOnly スクリプト、.npmignore、セマンティック バージョニング ガイダンス。

16. ローカル データベース (条件付き — ローカル データベース = yes の場合のみ含める)

src/db/schema.ts — Drizzle テーブル定義 (モデル ファイルから導き出されたすべてのエンティティ テーブル)。 src/db/client.ts — WAL モード、外部キー、および初回オープン時の自動マイグレーション ランナーを備えた better-sqlite3 シングルトン。 src/db/path.ts — env-paths ベースの OS データ ディレクトリ解決。 src/db/repositories/ — エンティティごとに 1 つのリポジトリ クラスで、型付き CRUD およびクエリ メソッドを公開します。drizzle.config.ts、drizzle/ マイグレーション フォルダ、および db:generate / db:migrate / db:studio npm スクリプト。 references/database-patterns.md を参照してください。

17. 非同期パターン (条件付き — 任意の非同期パターンが検出された場合のみ含める)

適用されるサブセクションのみを含めます。複数のサブセクションを一緒に含めることができます。

17a. 共有シグナル処理 (任意の非同期パターンが yes の場合は常に含める) src/utils/signal.ts — SIGINT および SIGTERM ハンドラーを登録し、クリーンアップ関数を実行してから、コード 130 (Ctrl+C) または 0 (SIGTERM) で終了する onSignal(cleanupFn) ユーティリティ。 ポーリング ループ、バッチ プロセッサ、およびデーモン ランナーで使用されます。Node.js スタック トレースではなくきれいな終了を保証します。

17b. ポーリング (ポーリング = yes の場合のみ条件付きで含める) src/utils/poll.ts — 設定可能な間隔、タイムアウト、スピナー統合、および onTick コールバック付き poll<T>(options) 関数。 コマンド ハンドラーは --watch / --follow / --wait フラグをポール ユーティリティに渡します。watch なし呼び出し (ファイア アンド フォーゲット) はフラグが不在の場合もサポートされる必要があります。 references/async-patterns.md を参照してください。

17c. インライン バッチ処理 (インライン バッチ = yes の場合のみ条件付きで含める) src/utils/batch.ts — 設定可能な同時実行性、エラー時の中止モード、アイテムごとのエラー コレクション、および onProgress コールバック付き runBatch<TInput, TOutput>(options) 関数。 src/ui/progress.ts — [percent%] n/total — ETA Xs を表示する ora ラッパーの ProgressBar。 ローカル データベース = yes の場合、再開パターンを含める: サービスは、バッチが開始される前にリポジトリをクエリして、既に処理済みの ID をアイテム リストからフィルターします。 references/async-patterns.md を参照してください。

17d. バックグラウンド デーモン (バックグラウンド デーモン = yes の場合のみ条件付きで含める) src/daemon/runner.ts — デーモンのイベント ループを実装する runDaemon() 関数; プロセスが Commander が引数をパースする前に環境で MY_TOOL_DAEMON_MODE=1 を検出するときに呼び出されます。 src/services/daemon.service.ts — DaemonManager クラス、start() (デタッチ スポーン)、stop() (SIGTERM + タイムアウト + SIGKILL)、isRunning() (信号-0 チェック)、getStatus()、 および getRecentLogs()。PID は conf に保存されます (ユーザー設定 = yes が必要)。 src/commands/daemon/index.ts — start、stop、status、logs サブコマンド。 references/async-patterns.md を参照してください。

各 <command-name>/SPEC.md (コマンドごと) に含まれるもの

PRD.md のコマンドごとに、コマンドにちなんで名付けられた (kebab-case) フォルダを作成し、その中に SPEC.md を生成します。各ファイルは 自己完結型 です — コーディング エージェントは共有インフラストラクチャが配置された後、コマンドを実装できます。

各コマンド SPEC.md は以下を含める必要があります:

• ヘッダー (コマンド名、ルート SPECIFICATION.md へのバックリファレンス)
• 追跡可能性: ユーザー ストーリー ID、NFR ID、制約 ID
• コマンド定義: すべての引数、オプション、説明文字列を含む完全な Commander.js .command() チェーン
• 引数 & オプション契約: 検証用 Zod スキーマ、完全なオプション フラグ テーブル
• プロンプト フロー (条件付き): インタラクティブ モード用の @inquirer/prompts シーケンス
• サービス インターフェース: このコマンドが TypeScript シグネチャを呼び出すメソッド
• サービス実装: 完全なビジネス ロジック、ターミナル I/O なし
• 出力契約: --json 出力と人間が読める出力の正確な構造、 ポーリングまたはインライン バッチがこのコマンドに適用される場合は非同期出力契約を含めます
• エラー ケース: すべてのエラー型、終了コード、およびユーザー向けメッセージ
• 完全なコード サンプル (すべてのコンポーネント用)

references/command-patterns.md で、シンプル コマンド、サブコマンド グループ、確認プロンプト、--dry-run、 表形式出力、グローバル オプション伝播、ヘルプ テキスト規約、および終了コード テーブルをカバーする標準的なコマンド登録パターンを参照してください。

Changelog 追加

すべての仕様書ファイルが正常に生成された後、アプリケーション フォルダの CHANGELOG.md (<app_folder>/CHANGELOG.md) にエントリを追加します:

1. <app_folder>/CHANGELOG.md を読みます。存在しない場合は以下で作成します:

   # Changelog
   
   - このファイルは、このアプリケーションのバージョン別の全スキル実行を追跡します。
   - このファイルに記録された最高バージョンは、現在のアプリケーション バージョンです。
   - スキルは、このファイルの最高バージョンより低いバージョンに対して実行されてはいけません。
   
   ---
   

2. 現在のバージョンと一致する ## {version} 見出しを検索します。
3. セクションが 存在する場合: そのテーブルに新しい行を追加します。
4. セクションが 存在しない場合: コンテキスト ヘッダー下の --- の後、既存の ## vX.Y.Z セクション (最新優先の順序) の前に新しいセクションを挿入します。新しいテーブル ヘッダーと最初の行を含めます。
5. 行の形式: | {YYYY-MM-DD} | {application_name} | specgen-ts-cli | {module or "All"} | Generated TypeScript CLI technical specification |
6. 既存の行を変更または削除しないでください。

出力フォーマット

<app_folder>/context/specification/
├── SPECIFICATION.md              ← ルート: TOC + 共有インフラストラクチャ
├── <command-1>/
│   └── SPEC.md                   ← 自己完結型コマンド ブループリント
├── <command-2>/
│   └── SPEC.md
└── <command-N>/
    └── SPEC.md

サンプル コードは必須です。 任意の仕様ファイルで説明されているすべてのコンポーネントは、完全で自己説明的なコード サンプルを含める必要があります。コードは連続 ( // ... ギャップなし) で、コーディング エージェントが直接参照として使用できます。

制約

これらの制約は交渉の余地がありません。生成された仕様内のすべてのコード サンプルはこれらに従う必要があります。

ユニバーサル制約

全体を通して ESM を使用します。 プロジェクトは package.json で "type": "module" を設定します。TypeScript ソースのすべてのインポートは .js 拡張子を使用します (TypeScript は .ts に解決されます)。 require() または CommonJS module.exports を使用しないでください。

any 型がありません。 すべての関数シグネチャ、変数、およびジェネリックを明示的に型指定する必要があります。any の代わりに、ランタイム絞り込み (Zod) を使用して unknown を使用します。

サービスのコンストラクタ注入。 サービスはそれらの依存関係 (設定、HTTP クライアント、ロガー) をコンストラクタを通じて受け入れます。サービス ファイルで直接インポートされたグローバル シングルトンがありません。これにより、モックを使用したクリーン ユニット テストが可能になります。

コマンドに業務ロジックを含めてはいけません。 コマンド action ハンドラーは薄いオーケストレータです: オプションを解析 → サービスを呼び出す → 出力をフォーマット → エラーを処理。すべてのドメイン ロジックは src/services/ に存在します。

出力をロジックから分離します。 サービス メソッドは型付きデータ構造を返します。コマンド ハンドラーはフォーマットと印刷を担当します。サービスは console.log を呼び出したり、ターミナル状態を操作したりしません。

常に終了コードを処理します。 すべてのコマンド action ハンドラーは本体を try/catch でラップします。エラー時: 書式設定されたメッセージを出力、process.exit(1) を呼び出します (または適切なコード)。成功時: process.exit(0) は暗黙的です。

ESM インポート パスは .js 拡張子を使用します。 TypeScript ソース ファイルで:

import { UserConfig } from '../config/user.config.js'  // ✓ 正しい
import { UserConfig } from '../config/user.config'      // ✗ 間違い

すべてのユーザー向け文字列がロガーまたは出力モジュールを経由します。 コマンドまたはサービスで console.log を直接呼び出さないでください。logger.info()、logger.error()、output.print() などを使用します。

すべての外部データに Zod を使用します。 設定ファイル、API レスポンス、または CLI 引数からの設定ファイル、API レスポンス、または CLI 引数からシステム境界を越えて渡されるデータは、使用前に Zod スキーマで解析される必要があります。

inquirer ではなく @inquirer/prompts を使用します。 モダン スコープ パッケージは公式にサポートされているバージョンです。レガシー inquirer デフォルトではなく、個別のプロンプト関数をインポートしてください。

条件付き制約

バイナリ パッケージング = yes の場合:

• pkg の静的解析と互換性のないモジュールの場合は、動的 import() を使用します
• __filename / __dirname を避けます — import.meta.url を `fileURLTo