Tsumiki Codexの使い方｜要件定義から実装までの導入手順

Tsumiki Codex連携を今確認する理由

Tsumikiは、曖昧な依頼からすぐコードを書き始めるのではなく、要件、設計、作業分解、テスト、実装を段階的に進めるための枠組みです。AIコーディングエージェントに大きな変更を任せるとき、先に判断材料と合格条件をそろえられる点に価値があります。Codexでも同じ考え方は使えますが、Tsumikiの配布物をCodexがそのまま理解するわけではありません。両者の間に設定形式の違いがあるため、変換と確認を分けて考える必要があります。

Tsumikiの公式リポジトリは、基本的にClaude Codeをサポートしつつ、rulesyncを組み合わせれば他のAIコーディングツールでも使用できると説明しています。対応対象の例にはcodexcliも含まれます。つまり「TsumikiがCodexへ直接追加された」のではなく、「Tsumikiの指示を別形式へ移す公式な道筋が示されている」と理解するのが正確です。

TsumikiはCodex専用の拡張ではない

Tsumikiには、要件定義から実装までを扱うKairo、テスト駆動で小さく進めるためのTDD、既存コードを調べて資料化するための機能群があります。各機能は、特定の順序で質問し、成果物を確認してから次へ進む長い指示として用意されています。Codexで利用する際も、名前だけを移すのではなく、確認の区切りや成果物の条件まで保てているかを見る必要があります。

特に注意したいのは、コマンドが表示されたことを「対応完了」と判断しないことです。変換後のMarkdownを開き、参照先、保存先、承認を求める箇所、利用できる道具の前提を確認します。元の指示に別製品固有の呼び出し方が残っていれば、Codex向けに読み替えるか、その工程を使わない判断が必要です。

2026年7月23日の更新で確認点が変わった

rulesyncの公式リリース v14.2.0は、2026年7月23日に公開されました。この版では宣言的なソース管理が追加され、GitHub、Git、npmを通じて設定元を扱う範囲が広がっています。Tsumikiのような外部の指示資産を複数のAIコーディングツールへ合わせる場合、元データと生成物を分けて管理する考え方が以前より重要になりました。

また、古い解説で見かける試験的なオプション名と、現行のCLI Commandsに載る--simulate-commandsは表記が異なります。過去の記事からコマンドをコピーするのではなく、利用時点の公式資料で引数を確認すべき理由です。本記事では、まず現行版の--dry-runを使い、書き込み前に差分を見る方法を採ります。

Tsumiki・rulesync・Codexの役割を分ける

三つの道具は同じ仕事をしているわけではありません。Tsumikiは「どの順に考え、何を成果物にするか」という開発手順を提供します。rulesyncは、あるAIコーディングツール向けに書かれたルール、コマンド、サブエージェント、Skillsなどを共通の入力へ取り込み、別の形式へ出力します。Codexは、変換された指示を読み、実際のリポジトリを調査、編集、検証する担当です。

この分担を理解すると、不具合の切り分けも容易になります。工程の順序や質問内容がおかしいならTsumiki由来の指示を確認し、ファイルが出ないならrulesyncの対象と機能指定を確認します。Codexが禁止事項を守らない場合は、変換ファイルだけでなくプロジェクトのAGENTS.mdが読まれているかを確認します。一つの道具に原因を決めつけず、入力、変換、実行の三層で見ることが大切です。

rulesyncは設定の通訳を担当する

rulesyncのSupported Tools and Featuresでは、Codex CLIの対象名がcodexcliと定義されています。ルール、MCP、サブエージェント、Skillsなどはプロジェクト単位と個人単位の対応範囲が表で示され、コマンドは個人単位の対応です。どの機能も同じ場所へ出力できるわけではないため、対象名だけでなく適用範囲も確認しなければなりません。

変換時は、TsumikiのClaude Code向けファイルをrulesyncの共通入力へ取り込み、そこからCodex用の形式を生成します。rulesyncが指示の正しさを保証するわけではなく、形式と配置先を合わせる役目です。生成後にMarkdownの内容を読む、git diffで変更範囲を見る、Codexを起動して候補が現れるか確かめる、という確認は利用者側に残ります。

個人用コマンドとSkillsを使い分ける

Codexの個人用コマンドは、手元だけで短期間試すには便利です。しかし、OpenAIのCustom promptsでは、この方式は非推奨とされ、新しく再利用可能な指示を整える場合はSkillsが案内されています。変換したTsumikiの工程を長く使うなら、個人用コマンドを最終形とせず、効果を確認した工程からSkillsへ移すのが堅実です。

Skillsはプロジェクト内に置いて共有でき、Codexがタスク内容に応じて選べます。一方、全案件へ共通する禁止事項を長大なSkillへ埋め込むと見落としやすくなります。リポジトリ全体で必ず守る条件はAGENTS.md、要件定義や設計レビューの詳しい進め方はSkills、個人が一時的に試すものはコマンド、と役割を分けると管理しやすくなります。

導入前に対象工程と安全条件を決める

Tsumikiには複数の工程があるため、初回からすべてを導入すると、どの指示が結果へ影響したのか分かりにくくなります。まずは「要件定義だけ」「既存コードの調査だけ」のように、入出力を説明できる一工程を選びます。対象リポジトリも、作業途中の重要案件ではなく、小さな検証用プロジェクトか、変更を破棄できるブランチが適しています。

次に、Codexが変更してよい場所、必ず実施するテスト、触れてはいけないファイル、成果物の保存先を決めます。これらはTsumikiの一般的な指示へ任せず、対象プロジェクトのAGENTS.mdや依頼文で明示します。外部のフレームワークは工程を整えてくれますが、自社の品質基準や製品固有の制約までは知りません。ローカルのルールを優先できる構造にしてから導入します。

最初は要件定義だけを選ぶ

要件定義は、コード変更を伴わず成果物を比較しやすいため、最初の試行に向きます。既存の課題を一つ選び、背景、利用者、必要な振る舞い、対象外、受け入れ条件が整理されるかを確認します。出力が抽象的なら、元のTsumiki指示に不足があるのか、変換で内容が欠けたのか、依頼時の情報が足りないのかを切り分けます。

要件定義の品質を確認できたら、次に設計、その次にテストと実装へ範囲を広げます。各段階で、人が承認する区切りが残っていることが重要です。前段の成果物が曖昧なまま次へ進むと、後から多くのコードを直すことになります。速さよりも、曖昧さを早い段階で発見できるかを初回評価の基準にします。

既存のCodex設定を先に確認する

変換前に、プロジェクト直下のAGENTS.md、.agents/skills、利用者ホームのCodex関連ディレクトリを確認します。既存ファイルがある場合は、名前と役割を控え、同名の生成物が予定されていないかを見ます。rulesyncの--dry-runは実ファイルを書かずに予定差分を確認できるため、最初の実行では必ず付けるのが安全です。

OpenAIのAGENTS.md公式資料によると、Codexは作業前にAGENTS.mdを読み、全体設定とプロジェクト固有の設定を階層に沿って組み合わせます。Tsumiki由来の指示を追加しても、この優先関係は変わりません。既存の品質基準と新しい工程が矛盾する場合は、生成物を直す前に、どちらを優先するかを決めます。

TsumikiをCodexで試す5つの手順

ここでは、Tsumikiの公式リポジトリを別ディレクトリに取得し、Claude Code向けのコマンドとサブエージェントをrulesyncへ取り込み、Codex用の個人設定として試す流れを示します。実際の案件リポジトリへ直接取得せず、変換専用の場所で内容を確認するのがポイントです。PowerShellやシェルの違いに応じて、行継続の書式は一行へまとめても構いません。

現行の対応表ではCodexのコマンドが個人単位になっているため、以下では--globalを明示します。新しいチーム共通資産を作ることが目的なら、この試行で効果を確認した後、次章のSkillsへ移してください。個人用コマンドをそのまま共有物として扱わないことが、将来の変更負担を抑えます。

Step 1: Tsumikiの公式リポジトリを別ディレクトリへ取得する

まず、作業中の製品リポジトリとは別の場所にTsumikiを取得します。URLは検索結果から選ばず、公式リポジトリを直接指定します。取得後はREADMEを読み、対象版で利用できるKairoやTDDの工程を確認してください。最新版の内容を無条件に全案件へ反映せず、試行に使う版を記録しておくと、後で差分を追いやすくなります。

git clone https://github.com/classmethod/tsumiki.git
cd tsumiki
git rev-parse --short HEAD

表示された識別子をメモし、記事や別の端末で見たコマンドと混ぜないようにします。Tsumiki側の更新でファイル構成が変わる可能性があるため、以降の操作で対象ディレクトリが存在しない場合は進めず、READMEの現行手順を確認します。

Step 2: Tsumikiの指示をrulesyncへ取り込む

次にrulesyncの入力を初期化し、Claude Code向けのコマンドとサブエージェントを取り込みます。init後に作られる.rulesyncが共通入力です。取り込み結果は生成物ではなく、変換元として扱います。処理が成功しても、ファイル数だけを見ず、要件定義や設計に相当するMarkdownが含まれるかを確認してください。

npx -y rulesync init
npx -y rulesync import --targets claudecode --features commands,subagents

公式Tsumiki READMEに過去の追加初期化コマンドが載っている場合でも、利用中のrulesync版で認識されるかを現行資料と照合します。不要な引数を足すより、まず最小の入力を作り、.rulesync内の内容が期待どおりかを読むほうが安全です。

Step 3: Codex向けの予定差分だけを表示する

書き込み前に、対象をcodexcliへ限定し、--dry-runで予定差分を表示します。コマンドは個人単位のため--globalを付けます。ここではまだ実ファイルを変更しません。既存の個人用コマンドやサブエージェントと同名の出力がないか、Tsumiki以外のファイルが削除対象になっていないかを確認します。

npx -y rulesync generate --targets codexcli --features commands,subagents --global --dry-run

現行CLIには--simulate-commandsもありますが、対応表でCodexコマンドは個人単位に対応しています。理由なく試験用変換を足さず、通常の個人単位出力を先に確認します。プロジェクト内へ置きたい場合はコマンド形式を無理に使わず、Skillsへの移行を選びます。

Step 4: 内容を確認してから個人環境へ反映する

dry-runの表示に問題がなければ、同じ指定から--dry-runだけを外して反映します。実行前にCodex関連ディレクトリの既存ファイルを退避し、生成後は追加・変更されたMarkdownを一つずつ開きます。外部コマンドの呼び出しや保存先が自分の環境に合わない場合は、Codexから呼び出す前に修正するか、そのファイルを利用対象から外します。

npx -y rulesync generate --targets codexcli --features commands,subagents --global

反映後はCodexを新しく起動し、コマンド候補とファイル名が一致するかを確認します。候補に出ない場合は、同じ生成処理を繰り返す前に、出力先、ファイル拡張子、Codexの読み込み対象を調べます。原因が分からないまま再生成すると、重複や上書きの判断が難しくなります。

Step 5: 要件定義だけを実案件の複製で試す

最初の利用では、製品リポジトリの複製または検証用ブランチを開き、要件定義に相当する一つのコマンドだけを呼び出します。コード変更は許可せず、課題の背景、対象範囲、対象外、受け入れ条件をMarkdownへまとめるよう依頼します。出力先を明示し、既存資料を上書きしない条件も加えます。

得られた文書は、元の課題と突き合わせて人が確認します。存在しない仕様を補っていないか、対象外が勝手に広がっていないか、検証可能な受け入れ条件になっているかを見ます。この一工程で安定した結果が出てから、設計や実装へ進むコマンドを追加します。

継続利用する工程はCodex Skillsへ移す

個人用コマンドで効果を確認できたら、頻繁に使う工程をSkillsへ移します。OpenAIのSkills公式資料では、SkillはSKILL.mdを中心とするディレクトリとして構成され、プロジェクト内にも配置できます。これにより、メンバーが各自のホームへ同じコマンドを入れなくても、リポジトリと一緒に工程を共有できます。

移行時は、Tsumikiの長い指示を一つのSkillへ丸ごと貼り付けないことが重要です。要件定義、設計レビュー、テスト準備のように、呼び出す目的ごとに分けます。各Skillの説明には「いつ使うか」を具体的に書き、本文には入力、成果物、確認の区切り、禁止事項を記します。対象が狭いほど、Codexが適切な場面で選びやすくなります。

Step 1: 一工程だけのSkillを作る

たとえば要件定義だけを移す場合、.agents/skills/tsumiki-requirements/SKILL.mdを作ります。名前には製品名だけでなく目的を含め、説明文で利用条件を示します。本文は、最初に既存資料を読み、疑問点を列挙し、人の回答を受けてから要件文書を作る順序にします。未確認の内容を事実として補わない条件も加えます。

---
name: tsumiki-requirements
description: 新機能の要件定義を整理し、対象範囲と受け入れ条件を文書化するときに使う
---

# 目的
課題と既存資料から、実装前に確認できる要件文書を作る。

# 進め方
1. 関連資料を読み、確定事項と未確定事項を分ける。
2. 未確定事項を質問し、回答を受けるまで実装へ進まない。
3. 対象範囲、対象外、受け入れ条件をMarkdownへまとめる。
4. 推測で補った箇所がないか確認し、結果を報告する。

この例を基点に、実際のTsumiki指示から必要な質問や成果物の構成を移します。参照する補助資料が多い場合はSkillと同じディレクトリへ置き、本文から必要なときだけ読むよう指定すると、毎回の指示が過度に長くなるのを防げます。

Step 2: 全体の禁止事項はAGENTS.mdに残す

Skillは特定の工程で選ばれるため、常に守るべき条件の置き場所には向きません。たとえば「既存資料を上書きしない」「外部パッケージを増やさない」「指定したテストを必ず実施する」といった全体条件は、プロジェクトのAGENTS.mdへ残します。Skill側には、その条件に従うことと、工程固有の追加条件だけを書きます。

配置後はCodexを新しく起動し、要件定義の依頼でSkillが選ばれるかを確認します。選ばれない場合は、説明文が抽象的すぎないか、ディレクトリ名とfrontmatterが正しいかを確認します。内容をむやみに増やすより、利用場面を具体化するほうが選択精度の改善につながります。

要件定義から実装まで段階的に進める

Tsumikiの価値は、多数のコマンドを増やすことではなく、前の成果物を確認してから次へ進める点にあります。Codexで使う場合も、要件定義、設計、作業分解、テスト、実装を一度の依頼へ詰め込みません。各段階でファイルを残し、人が承認した内容を次の入力にします。これにより、途中で前提が変わっても、どの成果物から直すべきか分かります。

また、工程ごとにCodexへ許可する行動を変えます。要件定義では読み取りと文書作成だけ、設計ではコード調査まで、実装では対象ファイルの編集とテストまで、というように範囲を広げます。最初から広い権限を前提にせず、その段階で必要な操作だけを許可すると、意図しない変更を減らせます。

要件定義では未確定事項を見える形にする

要件定義の成果物には、背景、利用者が達成したいこと、対象範囲、対象外、受け入れ条件、未確定事項を含めます。Codexには、資料から読み取れない内容を推測で確定しないよう指示します。未確定事項が残る場合は質問一覧として止め、人の回答を受けてから文書を更新します。

良い要件は、実装方法を細かく決める文書ではなく、完成を判定できる文書です。「使いやすくする」ではなく、誰がどの画面で何を完了できるか、失敗時に何が表示されるかを記します。Tsumiki由来の質問が多すぎる場合は、今回の変更に関係するものだけを残し、回答負担を抑えます。

設計では既存コードとの接点を示す

設計段階では、変更候補のファイル、既存機能との接点、データの流れ、失敗時の扱い、テスト方針を整理します。Codexにはコードをまだ変更させず、根拠となるファイルと行の位置を示させます。存在しない関数名や古い構成を前提にしていないか、人がリポジトリ上で確認します。

設計文書は、要件の各項目がどこで満たされるかを対応付けます。要件にない機能追加や大規模な整理が含まれていれば、その段階で外します。実装前に差分の大きさを見積もり、必要なら一つの変更をさらに分割します。設計の合意が取れるまで、コード編集へ進めないことが重要です。

実装ではテストを合格条件にする

実装段階では、先に失敗を再現するテストを用意し、その後で最小の変更を行います。Codexへの依頼には、対象ファイル、変更してよい範囲、実行するテスト、完了報告に含める内容を明記します。テストが通らない場合は、結果を隠さず原因と残課題を報告させます。

変更後は、テスト結果だけでなく、要件文書と実際の差分が一致するかを確認します。Tsumikiの工程を通ったから正しいのではなく、最初に決めた受け入れ条件を満たしたから完了です。不要な整形や名前変更が混ざっていれば分離し、レビューしやすい差分へ戻します。

Tsumiki Codex連携で起こりやすい問題

連携の失敗は、インストールできない場合だけではありません。コマンドは見えるが内容が古い、既存設定と同名で上書きされる、全工程が一度に走って確認の区切りが消える、といった問題もあります。見た目上は動いているため発見が遅れやすく、最初のdry-runと一工程だけの試行が重要になります。

問題が起きたら、Tsumikiの元ファイル、rulesyncの共通入力、Codex向け出力、Codexが実際に読んだ指示の順で確認します。どの層で内容が変わったかを特定できれば、再取得や再生成を繰り返さずに済みます。以下の観点を先に知っておくと、原因を短時間で絞れます。

古いオプション名をそのまま使う

過去のTsumiki READMEや紹介記事では、現行rulesyncと異なる試験用オプション名が載っている場合があります。エラーが出たときに似た名前を推測して追加せず、インストールされている版のヘルプと公式CLI資料を確認します。v14系の資料では--simulate-commandsが現在の名称です。

ただし、オプションが存在することと、Codexでその指定が必要なことは別です。現行対応表でコマンドは個人単位に対応しているため、まず通常の--global出力をdry-runで確認します。プロジェクト共有が必要なら、試験用変換へ寄せるよりSkillsへ移すほうが目的に合います。

既存の個人設定と名前が衝突する

個人環境には、すでに独自のコマンドやサブエージェントが置かれていることがあります。Tsumikiの生成物が同名なら、上書きによって以前の指示を失う可能性があります。反映前に既存ファイルを退避し、dry-runで追加、変更、削除の対象を確認してください。

衝突した場合は、生成物を直接継ぎ足して巨大な一ファイルにせず、用途が分かる名前へ変更するか、Skillsとして別ディレクトリに分けます。元データと手修正後のファイルを混ぜると、次回の生成で変更理由を追えなくなります。どれが生成物で、どれがプロジェクト固有の編集かを区別します。

全工程を一度に使って途中確認を失う

要件定義から実装までを一度に依頼すると、質問への回答を待つ区切りが効かず、Codexが仮定を置いたまま先へ進むことがあります。出力ファイルが多いほど確認した気になりやすいものの、最初の前提が違えば後続成果物もすべて影響を受けます。

工程ごとに依頼を分け、成果物を保存し、人が承認してから次へ進めます。各依頼の冒頭で、前段の確定文書を唯一の入力として示すと、会話中の曖昧な発言に引っ張られにくくなります。Tsumikiの長所である段階性を、Codex上でも保つことが重要です。

まとめ

TsumikiをCodexで使うときは、直接対応の拡張として扱うのではなく、Tsumikiの指示をrulesyncでCodex向けに変換する構成として理解します。2026年7月23日にrulesync v14.2.0が公開された今は、古い例をコピーせず、現行の対象名、機能、適用範囲、オプションを公式資料で確認する良いタイミングです。

最初は別ディレクトリで元データを取得し、要件定義だけを取り込み、--dry-runで予定差分を確認します。個人用コマンドで価値を確かめた後、継続利用する工程はSkillsへ移し、全体の禁止事項はAGENTS.mdへ残します。要件、設計、テスト、実装を段階的に進め、各成果物を人が確認することが、安全に活用する最短ルートです。