まず覚えること
📌 一番大事な前提

Codex.app は、設定作業そのものも自然文で依頼してよいツールです。
このページでは「ファイルを自分で編集する」よりも、Codex に日本語で依頼することを前提にしています。

このガイドで扱うもの
Dev Perfect Workflow、XeroPM Kanban Ops、team-architecture-mcp、xeropm-kanban-prod、xeropm-daily-report-prod、社内用パーソナライズ設定
このセットでできること
開発タスクの進め方・確認・記録を揃える / XeroPM の共有 Kanban を安全に確認・更新する / 本人の日報を Codex から下書き・保存する / 設計相談、責務分割、確認漏れチェックを行う
  • インストールや設定は、まず Codex に自然文で頼む
  • 個人 token だけは管理者から受け取り、自分で貼り付ける
  • 入れた後は「何ができるか」をプロンプト例でそのまま試す
📌 人が自分でやる作業は主に 3 つ
1. GitHub からこのリポジトリを取得する
2. Codex.app の Custom Instructions に文章を貼る
3. 必要なら管理者から受け取った token を .env に入れる
何を入れるのか
1
スキル
Codex に「仕事の進め方」や「特定業務のコツ」を覚えさせる追加知識です。今回は Dev Perfect WorkflowXeroPM Kanban Ops を使います。
2
MCP サーバ
Codex が外部サービスに安全につながる窓口です。今回は team-architecture-mcpxeropm-kanban-prodxeropm-daily-report-prod を使います。
3
パーソナライズ
Codex の基本姿勢を固定する設定です。社内標準の言い回し、説明の粒度、確認の仕方を最初から合わせられます。
⚠️ よくある誤解
スキルと MCP は別物です。スキルは「考え方と手順」MCP は「接続先」です。両方あると、自然文だけでかなり実務に使える状態になります。
対象バージョン
対象 バージョン 補足
KCSポータルの Codex活用ガイド ver 1.2.78 このページ自体の公開バージョンです。
Dev Perfect Workflow v1.1.7 Codex.app のスキル一覧で確認した表示バージョンです。
XeroPM Kanban Ops v1.2.2 Codex.app のスキル一覧で確認した表示バージョンです。
社内スキル資産の追跡用 commit codex-skills main@842f2f9 xerographix/codex-skills リポジトリの確認時点 commit です。
team-architecture-mcp version表記なし production endpoint で運用しています。画面上で見える版番号はありません。
xeropm-kanban-prod version表記なし 共有 Kanban 用 MCP です。URL と環境名で区別します。
xeropm-daily-report-prod version表記なし 本人の日報用 MCP です。Authorization: Bearer <個人 token> を直接設定します。
導入前に必要なもの
先に確認するもの
Codex.app、Git、GitHub からの取得権限、必要に応じて XeroPM の個人 token
  • Codex.app がインストール済みである
  • Git が使える
  • GitHub からこのリポジトリを取得できる
  • XeroPM を使う人は、必要に応じて管理者から個人 token を受け取れる
  • 共有 Kanban だけなら個人 token は不要
  • 本人の日報保存まで使うなら、管理者から個人 token を受け取る
📌 token が必要なのはここだけ
xeropm-daily-report-prod を使って本人の日報を保存する場合だけ、管理者から受け取った個人 token が必要です。
共有 Kanban の確認や更新だけなら、個人 token なしでも進められます。
自然文だけで入れる手順

Step 0. GitHub から取得する

場面 実行する内容
初回取得 git clone https://github.com/xerographix/codex-skills.git
cd codex-skills
すでに取得済み cd codex-skills
git pull

Step 1. Codex.app でこのリポジトリを開く

  1. Codex.app を開く
  2. このリポジトリのフォルダを開く
  3. Codex に次のどちらかを依頼する
このリポジトリのスキルをインストールして。
この codex-skills リポジトリから利用可能なスキルをインストールして。

Step 2. まず、今の状態を確認する

今の Codex.app に、Dev Perfect Workflow、XeroPM Kanban Ops、team-architecture-mcp、xeropm-kanban-prod、xeropm-daily-report-prod が入っているか確認して。不足があれば一覧で教えて。

Step 3. 社内スキルを GitHub から入れる

https://github.com/xerographix/codex-skills.git から Dev Perfect Workflow と XeroPM Kanban Ops をインストールして。終わったら再起動が必要かも教えて。

Step 4. 共通 MCP を追加する

team-architecture-mcp と xeropm-kanban-prod を Codex.app に追加して。既存設定があれば上書きせず、差分だけ整えて。
用途 名前 URL 補足
設計チェック用 MCP team-architecture-mcp https://team-architecture-mcp-prod-xncdzverwq-an.a.run.app/mcp 設計相談、責務分割、確認漏れチェックに使います。
共有 Kanban 用 MCP xeropm-kanban-prod https://xeropm-kanban-mcp-prod-131236897984.asia-northeast1.run.app/mcp 共有 Kanban の確認・更新用です。

Step 5. 個人日報 MCP を追加する

7-1. まず管理者に token を発行してもらう
管理者から受け取るものは、本人用の XeroPM 個人 token 文字列です。
TOKEN発行 管理者用
📌 7-2. Codex.app に token を直接設定する
.env には入れません。 Codex.app の xeropm-daily-report-prod 設定画面で、Authorization ヘッダーに token を直接入れます。
設定欄 入れる値
URL https://xeropm-kanban-mcp-prod-131236897984.asia-northeast1.run.app/mcp
Bearer トークン環境変数 空にする
ヘッダーのキー Authorization
ヘッダーの値 Bearer <管理者から受け取った個人 token>
  • Authorization の値は Bearer <token> 形式にする
  • Bearer と token の間は半角スペース 1 つ
  • 前後に空白を入れない
  • token を他人に送らない
  • 設定後は Codex.app を再起動して反映を確認する
項目
名前 xeropm-daily-report-prod
URL https://xeropm-kanban-mcp-prod-131236897984.asia-northeast1.run.app/mcp
Authorization Bearer <管理者から受け取った個人 token>
管理者からもらった token を使って、本人の日報用 MCP を設定して。名前は xeropm-daily-report-prod、URL は https://xeropm-kanban-mcp-prod-131236897984.asia-northeast1.run.app/mcp、Authorization ヘッダーに Bearer <token> を入れて。xeropm-kanban-prod は共有 Kanban 用として残して。
Codex に依頼するなら、こう言えば大丈夫です。 管理者からもらった token を使って、xeropm-daily-report-prod を設定して。URL は https://xeropm-kanban-mcp-prod-131236897984.asia-northeast1.run.app/mcp、Authorization ヘッダーは Bearer <token> にして。xeropm-kanban-prod は共有 Kanban 用として残して。
⚠️ 重要
xeropm-kanban-prod を上書きせず、xeropm-daily-report-prod を別で作る運用にします。

Step 6. パーソナライズ設定を入れる

次の社内向け初期プロンプトを、Codex.app の Custom Instructions に入れて。既存内容があれば消さずに整理して統合して。
補足
スキルを新規インストールした直後は、Codex.app の再起動を案内されたらその通りに実施します。
📌 デプロイ運用の社内標準
production 反映は、ローカル PC から直接 `firebase deploy` / `gcloud run deploy` を打たず`main` への push を起点に GitHub Actions で自動採番・自動デプロイする運用に統一します。ローカルからの直接デプロイは、障害対応や workflow 異常時の例外対応だけにします。

Step 7. 導入確認をする

共通確認
インストール済みの skill と MCP を確認して。
設計チェック MCP
team-architecture-mcp の list_available_profiles を試して。
共有 Kanban
私の担当タスクを XeroPM の Kanban から取得して。
本人日報 MCP
個人日報MCPで get_me を試して。次に list_my_daily_report_context を試して。
⚠️ 最終確認はこのプロンプトをそのまま使う
スキルや MCP が本当に使えるかを最後に確認したい時は、下の文面をそのまま Codex に貼ってください。壊さない範囲で最小の smoke test をさせるための確認用です。
MCP とスキルが正しく入っているか確認したい。以下の順で、壊さない範囲で最小限の smoke test を実行して、最後に「入っている / 使えない / 設定不足」を一覧で報告して。 前提 - 既存データを変更しない - 破壊的操作はしない - 何か不足していたら、その時点で止めて不足内容を明記する - 使う前に、各 skill / MCP を名指ししてから実行する 確認したいもの 1. dev-perfect-workflow - この会話の方針に従って、開発タスク向けのチェック観点を1回だけ短く適用してみて - 「使える / 使えない」を明記して 2. team-architecture-mcp - 利用可能なら tools/list を確認して - そのあと review_worktree か check_release_readiness のどちらかを最小入力で試して - 結果と、設定不足があればそれを明記して 3. xeropm-kanban-prod - 共有 Kanban 用として利用可能か確認して - 破壊しない最小ツールで疎通確認して - 例: list_projects か list_kanban_tasks 4. xeropm-daily-report-prod - 個人日報用として利用可能か確認して - 破壊しない最小ツールで疎通確認して - 例: get_me か list_my_daily_report_context 5. magic-xpa-mcp - 利用可能なら tools/list または list_supported_operations を確認して - 破壊しない最小ツールで疎通確認して - 使えない場合は、何が足りないかを明記して 出力形式 - まず「確認対象の一覧」 - 次に各項目について - スキル / MCP 名 - 使えたか - 実行した最小確認 - 結果 - 不足やエラー - 最後に - 全体まとめ - 次に直すべき設定 - 使い始めるための最短手順 を箇条書きで出して
実際の使い方
9-1. 開発タスク
この不具合を修正して。必要な確認も進めて。
  • `dev-perfect-workflow` が使われる
  • 影響範囲が先に出る
  • `docs/PROGRESS.md` に追記する
  • 設計確認が必要なら `team-architecture-mcp` を使う
9-2. 設計相談
この変更は Controller に置くべきか Service に置くべきか、team-architecture-mcp を使って確認して。
9-3. Kanban 確認
白木商店のタスクを XeroPM の Kanban で確認して。
9-4. Kanban 更新
白木商店の要件定義タスクを確認して、必要なら進捗を更新して。
9-5. 日報の下書き
本人の日報MCPで今日の日報を下書きして。9:00-10:00 はきもの365調査、10:00-11:00 は白木商店要件定義。内容が薄ければ補って。
9-6. 日報の保存
本人の日報MCPで今日の日報を保存して。9:00-10:00 はきもの365調査、10:00-11:00 は白木商店要件定義。足りない情報があれば質問して。
うまく動かない時の確認ポイント
スキルが見えない
  • Codex.app を再起動する
  • リポジトリを開き直す
  • Codex に再度依頼する
このリポジトリのスキルをもう一度インストールして。
XeroPM の日報 MCP が動かない
  • Authorization ヘッダーが入っているか確認する
  • 値が Bearer <token> 形式か確認する
  • token の値が空でないか確認する
  • Codex.app を再起動する
この環境で xeropm-daily-report-prod の Authorization ヘッダー設定が正しいか確認して。 個人日報MCPの get_me が通るか確認して。
設計チェック MCP が動かない
`team-architecture-mcp` の URL が正しいか確認します。
正しい URL https://team-architecture-mcp-prod-xncdzverwq-an.a.run.app/mcp 確認依頼の例 team-architecture-mcp の接続先が正しいか確認して。
更新方法
📌 スキル資産を更新したい時
まずローカルの `codex-skills` リポジトリを更新します。
cd codex-skills git pull
このリポジトリを最新版として、スキルと MCP の設定状態を確認して。必要ならローカルのインストール先も最新化して。
本人日報用 token を使っている場合
今は .env ではなく、xeropm-daily-report-prodAuthorization ヘッダーに直接入れる方式です。管理者が token を再発行した場合は、MCP 設定画面のヘッダー値を新しい token に差し替えてください。
管理者に依頼すべき内容
1
個人日報を使いたい時
本人用の個人 token は管理者発行です。自分で仮の値を作らず、管理者から正式な token を受け取ってください。
Codex の本人日報MCPで使うための個人 token を発行してください。
スキルの使い方と価値
Dev Perfect Workflow
開発タスクを雑に進めず、影響範囲、進捗、検証、ロールバックまで揃えてくれるスキルです。
  • 変更前に影響範囲を宣言させられる
  • 進捗ログや README 更新漏れを減らせる
  • 検証結果と戻し方まで残せる
この不具合を直して。変更前に影響範囲を出して、実装後は確認結果とロールバック方法もまとめて。
XeroPM Kanban Ops
XeroPM の Kanban を、案件違いや重複起票を避けながら安全に操作するスキルです。
  • 正しい顧客・案件を先に特定する
  • 既存カードがあれば新規起票より更新を優先する
  • 日報とのズレ確認にもつなげやすい
白木商店の受入テストカードを探して、まだ実行せずに更新予定だけ見せて。
MCP サーバの使い分け
A
team-architecture-mcp
設計・構成の相談向けです。アーキテクチャの候補比較、責務分割、リスク洗い出し、レビュー観点の整理に向いています。実装前後の品質確認にも使えます。
B
xeropm-kanban-prod
共有 Kanban 操作用です。顧客名やプロジェクト名が曖昧でも、候補を確認しながら安全にカードを扱えます。
C
xeropm-daily-report-prod
本人の日報用です。共通 Kanban 用とは分けて使い、個人 token で本人の日報だけを扱います。
📌 設計思想の統一にも効く
team-architecture-mcp は、単に案を出すためだけではなく、設計の判断軸を揃えるためにも役立ちます。
「どこに置くべきか」「責務をどう分けるか」「依存方向は自然か」を、毎回同じ観点で見られるようになるためです。
実務で特に使いやすい確認
`review_worktree`、`list_required_checks`、`check_progress_doc_sync`、`check_release_readiness` を使うと、設計逸脱、確認漏れ、進捗記録漏れ、push 前の不足を見つけやすくなります。
⚠️ なぜ設計思想が大事か
設計思想が揃っていないと、人によって置き場所や分け方がぶれます
その結果、レビューが好みの話になりやすく、修正のたびに迷いが増えます。
逆に、設計思想が揃うと、実装・レビュー・引き継ぎの判断が速くなり、品質も安定しやすくなります
設計相談の依頼例
team-architecture-mcp を使って、この案件の画面構成と API 分割案を出して。初心者にも分かる言葉で、候補ごとのメリット・デメリットを比べて。
Kanban 更新の依頼例
xeropm-kanban-prod を使って、きもの365 の未担当タスクを探して。まだ更新しないで、候補カードと変更予定だけ見せて。
日報保存の依頼例
本人の日報MCPで今日の日報を保存して。9:00-10:00 は白木商店 QA 整理、10:00-12:00 は販売管理の請求書機能調査。足りない情報があれば質問して。
バックグラウンドエージェントの使い方
📌 何ができるのか
ひとつの会話の中で、別のエージェントに並行作業を任せる使い方です。
たとえば、ローカル環境の起動・停止役コードレビュー役別観点の調査役を分けると、メインの作業を止めずに進めやすくなります。
向いている使い方 1
ローカルサーバの起動・停止、ログ監視、URL 案内など、主作業の横で動かしたい役割
向いている使い方 2
原因候補の洗い出し、差分レビュー、別案の比較など、並行で見たい調査
向いている使い方 3
ひとつのエージェントに全部やらせず、実装役と確認役を分けたいとき
⚠️ 使い方の注意
すぐ答えが必要な作業や、今まさに詰まっている本筋は、メインの Codex にそのままやらせた方が速いです。
バックグラウンドエージェントは、止めずに横で進めたい作業に向いています。
また、同じファイルを複数エージェントに同時編集させない方が安全です。
おすすめの頼み方 役割: 何を任せるか: 欲しい結果: まだ実行してよいか: 例: バックグラウンドエージェントを起動して、ローカル環境の起動と停止だけ担当させて。私はブラウザ確認だけしたい。起動URLと停止方法も最後に教えて。
起動役の依頼例
バックグラウンドエージェントを起動して、このリポジトリのローカル環境を起動・停止できるようにして。私はブラウザで見た目だけ確認したい。URL も教えて。
調査役の依頼例
別のバックグラウンドエージェントで、この不具合の原因候補を先に洗って。本体は修正方針を考えて。結果は原因候補を3つまでに絞って。
レビュー役の依頼例
レビュー専用のバックグラウンドエージェントで、この差分の危険点だけ先に見て。要約ではなく、バグや見落としだけ教えて。
パーソナライズの入れ方
📌 何のために入れるのか
毎回「日本語で」「初心者向けに」「危険な変更は先に確認して」と言わなくても、最初からその方針で返してくれるようにするためです。
⚠️ 大事な注意
パーソナライズだけでスキルが新規インストールされるわけではありません。スキルが既に入っている前提で、そのスキルを使う確率と一貫性を上げるための設定です。
Codex.app の Settings から Personalization を開いて、社内標準の初期プロンプトを入れて。いまの設定があれば消さずに整理して、重複や矛盾がない形にまとめて。

Settings > Personalization > Custom instructions に貼る文面

返答は、ユーザーの言語に合わせる。日本語なら日本語、英語なら英語で返す。混在している場合は、相手が主に使っている言語を優先する。専門用語は必要最小限にし、使う場合は短く補足する。まず結論、その後に理由を述べる。曖昧な一般論より、実行可能な次の一手を優先する。 開発タスク(実装/修正/リファクタ/テスト/レビュー対応)では、常に dev-perfect-workflow を適用する。明示がなくても使う。該当しそうなら迷わず適用する。通常の自由回答より、dev-perfect-workflow の手順遵守を優先する。 作業開始時に、影響範囲を1行で宣言する(変更ファイル/画面/機能)。 要求は実装前に、目的 / 成功条件 / 制約 に分けて整理する。不明点や仕様の揺れがある場合は、推測で進めず、実装前に質問して確定する。 実装中は、進捗を docs/PROGRESS.md にステップごとに追記する。仕様変更、方針変更、追加調査、確認結果も記録する。 実装は最小差分を基本とし、関連ドキュメント、README、画面文言、運用手順、バージョン表記も必要に応じて同期する。 既存挙動を変更する場合、または本番影響がある変更を行う場合は、変更内容、影響範囲、前提条件、ロールバック方法を明確にする。 危険な操作、大量更新、削除、認証変更、設定変更、外部公開、本番反映につながる操作は、実行前に確認する。まだ実行しない依頼では、実行せず予定だけを示す。 team-architecture-mcp が使えるときは、設計相談、責務分割、構成比較、レビュー観点整理だけでなく、実装前後の品質確認にも積極的に使う。利用可能な場合は、review_worktree / list_required_checks / check_progress_doc_sync / check_release_readiness を優先して使い、設計逸脱、確認漏れ、進捗記録漏れ、push可否を判断する。 実装後は必ず確認を行う。少なくとも、実機確認手順、ログ確認手順、テスト手順と結果を提示する。未実施の確認がある場合は、未実施理由と残リスクを明記する。 最終報告には、変更サマリ、影響範囲、検証手順と結果、仕様変更差分、ロールバック方法、リリース影響、バージョン対応を必ず含める。 コード更新がある場合は、必要に応じてUI表示バージョンや関連履歴も更新対象として確認する。 文字化けした文書や不正な表示を見つけた場合は、壊れたまま編集せず、まず文字コードや読み込み状態を確認してから扱う。 XeroPM の Kanban 操作、日報、タスク整理、進捗確認の依頼では、インストール済みなら XeroPM Kanban Ops と関連 MCP を優先して使う。案件特定、重複確認、変更予定の提示を先に行い、不明なまま決め打ちしない。 xeropm-kanban-prod が使えるときは共有 Kanban 操作に使い、xeropm-daily-report-prod が使えるときは本人の日報操作に使い分ける。共通 Kanban と個人日報の用途を混同しない。 実行後は、何を変えたか、何を確認したか、次に何をすればよいかを簡潔に示す。
そのまま使える依頼文
📌 社内でおすすめする使い方
先に技術的なやり方を自分で決めないことをおすすめします。
まず「何を実現したいか」「何に困っているか」「何は避けたいか」だけを伝え、Codex に実装案を提案させる
選択肢が出たら人が選び、その後で 選んだ案を実行させる 使い方が、いちばん品質を安定させやすいです。
提案の中で分からない言葉や仕組みがあれば、その場で質問して理解しながら進めると、自分のスキルアップにもつながります。
良い理由 1
人が技術手段を決め打ちしないので、Codex がより筋の良い実装案を出しやすくなります。
良い理由 2
人は要件・優先順位・禁止事項の判断に集中でき、技術の細部は Codex に考えさせられます。
良い理由 3
最終的な選択は人が持つため、AI任せにしすぎず、社内標準に沿った意思決定がしやすくなります。
⚠️ ここがポイント
技術指示はしなくてよいですが、要件・成功条件・避けたいことは必ず伝えます。
ここが曖昧だと、提案の質がぶれます。
📌 スキルアップも意識する
Codex の提案の中で、自分が理解できない内容は必ず質問することをおすすめします。
「なぜその案が良いのか」「他の案より何が有利か」を聞くことで、人間側の理解と判断力も少しずつ上がります
ただ実行させるだけで終わらせず、分からない点はその場で確認する使い方が、長期的にはいちばん強いです。
おすすめの依頼テンプレ やりたいこと: 困っていること: 成功条件: 避けたいこと: まず実装案を出して。選んだ後に実装して。
良い依頼の例
画面が重い。利用者が待たないように改善したい。見た目は大きく変えたくない。まず改善案を2つか3つ出して、メリット・デメリットを比べて。その後、選んだ案で実装して。
避けたい依頼の例
React の useMemo と debounce を入れて API を叩く回数を減らして。

こうすると、人が先に技術手段を固定してしまい、もっと良い案を Codex が出しにくくなります。

利用場面別の依頼例

開発を始める
この不具合を修正して。必要な確認も進めて。
実装方針を相談する
この変更はどこに置くべきか確認して。必要なら team-architecture-mcp を使って。
Kanban を確認する
XeroPM の Kanban で、私の担当タスクを一覧で出して。
日報を保存する
本人の日報MCPで今日の日報を保存して。足りない情報があれば質問して。
📌 日報保存で質問に切り替わるのは正常
日付、開始時刻、終了時刻、顧客、プロジェクト、内容が足りないと、Codex はそのまま保存せずに質問へ切り替えます。
曖昧なまま保存させないための動きなので、ここは省略せずに埋めてもらう方が安全です。
  • Dev Perfect Workflow を使って、この修正の影響範囲と確認手順つきで進めて
  • XeroPM Kanban Ops を使って、この案件の重複カードがないか確認してから必要なら起票して
  • team-architecture-mcp を使って、この設計の責務分割をレビューして
  • 本人の日報MCPで、今日の日報を下書きして。不足があれば質問して
  • まだ実行しないで、設定変更の予定だけ見せて
⚠️ うまくいかないときの言い方
「設定できなかったら、何が足りないかだけ短く教えて」「まだ実行せず確認だけして」と一言足すと、失敗しにくくなります。
活用するメリットと価値
設定コスト削減
手で設定ファイルを触らなくても、自然文で導入を頼みやすくなります。
品質の底上げ
開発タスクの進め方が揃い、説明漏れ・検証漏れ・戻し方漏れが減ります。
誤操作の予防
XeroPM の案件違い、重複起票、日報と Kanban のズレに気づきやすくなります。
教育コスト削減
低リテラシ向けでも、やってほしいことを日本語のまま依頼しやすくなります。
この構成が向いている人
  • ターミナルや設定ファイルの手作業が苦手
  • まずは日本語で依頼して、Codex に設定や調査を進めさせたい
  • 開発と XeroPM 運用を同じツール上で自然につなげたい