📦

dotkiro で Kiro の組織標準を配布する — 標準リファレンス構成の展開実装

に公開

サマリ

  • Kiro の steering / skills を組織標準として整備しても、各プロジェクトへの配布と更新伝播 の仕組みがないと形骸化する
  • Kiro Labs の dotkiro は、中央 Git リポジトリに置いた conventions を各プロジェクトに sync する CLI
  • 配布モデルは「中央 Repo が Single Source of Truth、CLI が配送路、Pull Request が変更管理、manifest が追跡
  • CCoE 側は 配布の摩擦がなくなり、変更管理が Git に一本化される。事業部側は オンボーディングと日常運用が劇的に単純になる
  • types 概念で「共通標準」+「言語・フレームワーク・チーム別標準」を多層化できる。標準リファレンス構成(Paved Road)パターンの自然な拡張
  • Labs プロジェクトゆえの公式サポート外という制約はあるが、組織標準配布の参照実装 として試す価値は高い

はじめに — steering を書けても「配る仕組み」がないと形骸化する

以前「Kiro IDE /quick-spec を標準リファレンス構成の展開に活用する」という記事で、CCoE(Cloud Center of Excellence)が整備した標準リファレンス構成を Kiro の steering として配布し、/quick-spec で組織横断に spec を量産する運用を論じた。

その記事では意図的に「steering をどう書くか」に寄せた。しかし実運用で次にぶつかる問いは「書いた steering をどうやって各プロジェクトに行き渡らせるか」である。

単発でコピーすれば済むなら話は早いが、エンタープライズ開発では以下が継続的に発生する。

  • 新規プロジェクトが次々に立ち上がる(新規取得の手間
  • 組織標準自体がアップデートされる(伝播の手間
  • 複数の事業部・ベンダーで並行稼働している既存プロジェクトに反映する必要がある(後方展開の手間
  • 言語 / フレームワーク別に微妙に異なる標準を組み合わせたい(組み合わせの手間

これらを手動オペレーションに任せると、典型的な「標準の形骸化」が起きる。標準は GitHub にあるのに、各プロジェクトの .kiro/steering/ の中身は全部違う、という状態である。

Kiro Labs の dotkiro はこの問題を構造的に解く CLI ツールで、中央 Git リポジトリを Single Source of Truth にして、各プロジェクトに steering / skills を配布する メカニズムを提供する。本記事では CCoE と事業部の両視点から dotkiro の運用モデルを整理し、標準リファレンス構成の展開手段として評価する。

1. 配布メカニズムの選択肢

標準を中央管理して配布する課題は、Kiro に限らず多くの組織が過去に直面してきた。選択肢を整理するとこうなる。

手段 更新伝播 組み合わせ 新規適用 痛点
手動コピー なし 手動で切り貼り 毎回コピー 形骸化の主因、追跡不可
Git submodule 手動 pull submodule の入れ子で可能 submodule init 運用の学習コスト、差分管理が重い
Git subtree 手動 pull 同上 subtree pull submodule より柔軟だが煩雑
Monorepo 化 常に最新 ディレクトリ参照で可能 Monorepo 前提の構成変更 組織が Monorepo を採用していない場合は不可
自前スクリプト + npm 配布 バージョンで固定 実装次第 npm install && npx 自前実装の保守コスト
dotkiro dotkiro update types レイヤリング dotkiro init Labs プロジェクト、公式サポート外

dotkiro「自前スクリプト + npm 配布」の Kiro 特化版 と考えると位置付けがわかりやすい。Kiro の .kiro/steering/.kiro/skills/ のディレクトリ構造を前提にした振る舞いがビルトインされているので、汎用ツールを組み合わせるより摩擦が少ない。

2. dotkiro の動作モデル

dotkiro の設計は以下の 4 要素で構成される。

  1. 中央 Git リポジトリ: 組織の steering / skills の Single Source of Truth
  2. プロジェクト側の .dotkirorc: 中央 Repo の URL、使用する types、参照ブランチを記述
  3. .dotkiro-manifest.json: dotkiro が配置したファイルを追跡するローカル状態(commit しない)
  4. dotkiro CLI: 中央 Repo から pull して、各プロジェクトの .kiro/steering/ / .kiro/skills/ に sync


dotkiro の動作デモ(kirodotdev-labs/dotkiro より引用、Apache-2.0)

2.1 中央 Repo のディレクトリ構造

中央 Repo は以下の構造を取る。

my-conventions/
  steering/              ← shared。常に pull される
    code-style.md
    security.md
  skills/                ← shared。常に pull される
    code-review/
      SKILL.md
  python/                ← type: python
    steering/
      python-rules.md
    skills/
      pytest-helper/
        SKILL.md
  cdk/                   ← type: cdk
    steering/
      construct-patterns.md

shared がルートの steering/skills/ に置かれ、それ以外のディレクトリ名が type として扱われる。types は言語 / フレームワーク / チーム / 環境、何でもよい(Python / CDK / Platform Team / Production / Regulated など)。

2.2 types によるレイヤリング

プロジェクト側で dotkiro init python cdk を実行すると、shared の全ファイル + python の全ファイル + cdk の全ファイル が、プロジェクトの .kiro/steering/.kiro/skills/ に展開される。

.kiro/
  steering/
    code-style.md           ← shared
    security.md             ← shared
    python/
      python-rules.md       ← python type
    cdk/
      construct-patterns.md ← cdk type
  skills/
    code-review/
      SKILL.md              ← shared
    pytest-helper/
      SKILL.md              ← python type

steering はサブフォルダを Kiro がサポートするので type ごとにネストし、skills はフラット構造で取り込まれる。

この shared + type 積み重ね の構造は、標準リファレンス構成の階層的な整理と相性が良い。以下のような組織標準の分解に対応できる。

  • shared: 全プロジェクト共通(セキュリティベースライン、命名規約、タグ付け規約)
  • type: lambda: Lambda プロジェクト標準(Runtime 固定、Cold Start 対策、Secrets Manager 取得パターン)
  • type: ecs: ECS プロジェクト標準(タスク定義テンプレート、ログドライバ設定)
  • type: regulated: 規制業界プロジェクト標準(暗号化要件、ログ保全期間、監査ログ要件)

2.3 .dotkirorc と manifest の役割

プロジェクト側の設定ファイル .dotkirorc は、リポジトリに commit する

{
  "repo": "https://github.internal.example.com/platform/kiro-conventions.git",
  "branch": "main",
  "types": ["lambda", "regulated"]
}

これが commit されていれば、新しくクローンした開発者は dotkiro init 一発で、そのプロジェクト専用の組織標準が揃う

一方、.dotkiro-manifest.json は「dotkiro が今回配置したファイル一覧」をローカル追跡するもので、commit してはいけないdotkiro init --gitignore で自動的に .gitignore に追加できる。

manifest の存在によって、dotkiro は以下を安全に実現している。

  • 更新時: manifest に載っているファイルだけを更新・削除、手元で追加した .md は触らない
  • 削除時: dotkiro remove で manifest に記録された範囲だけを消す、カスタム steering は残る
  • 追跡: 「この file はどの type 由来か」を即座に参照できる

2.4 ブランチでバージョニングする

--branch オプションで中央 Repo の任意のブランチを参照できる。

dotkiro init lambda --branch=v2

中央 Repo で v1 / v2 / v3 のように長期保守ブランチを切っておけば、破壊的変更をした場合でも、既存プロジェクトは v1 に pin したまま運用できる。新規プロジェクトから v2 を使う、というタイミングを事業部側で選べる。

この柔軟性は、エンタープライズの「一斉移行は困難」という現実に適合する。

3. 運用フロー: CCoE と事業部の役割分担

ここから実運用の話に入る。CCoE と事業部の役割はこう分かれる。

3.1 CCoE: 中央 Repo をセットアップする

CCoE が中央 Repo をセットアップし、組織標準を投入する。以下のような構造が現実的。

kiro-conventions/              ← 組織の中央 Repo
  steering/
    org-security-baseline.md
    org-naming-conventions.md
    org-tagging-conventions.md
    org-iam-minimum-permissions.md
  skills/
    security-review/
      SKILL.md
    cost-review/
      SKILL.md
  lambda/
    steering/
      lambda-runtime-standard.md
      lambda-cold-start-guidance.md
      lambda-secrets-manager-pattern.md
    skills/
      lambda-cost-check/
        SKILL.md
  cdk/
    steering/
      cdk-typescript-standard.md
      cdk-construct-patterns.md
  ecs/
    steering/
      ecs-task-definition-standard.md
  regulated/                    ← 規制業界向け追加標準
    steering/
      regulated-encryption.md
      regulated-audit-logging.md

shared に組織全体の必須標準を置き、types に言語 / フレームワーク / 業界別の追加標準を分類する。各 Markdown は CODEOWNERS で所管部署が明示されている のが望ましい(セキュリティチームが security ステアリングを、ランタイムチームが lambda ステアリングを所有、のような)。

3.2 事業部: プロジェクトに組織標準を導入する

事業部が新規プロジェクトを立ち上げる際、.dotkirorc をコミットするだけで、組織標準が自動適用される。

{
  "repo": "https://github.internal.example.com/platform/kiro-conventions.git",
  "branch": "main",
  "types": ["lambda", "regulated"]
}

新メンバーが参加した時の手順も簡潔になる。

git clone <project-repo>
cd <project>
dotkiro init

これで .kiro/steering/.kiro/skills/ に「この事業部で、この規制業界向け Lambda プロジェクトの開発標準」が揃う。ここから /quick-spec を叩けば、前回記事で述べた通り、組織標準に沿った spec が生成される。

3.3 CCoE × 事業部: 標準更新のサイクル

もっとも重要なのが、組織標準の更新が PR ベースで全組織に伝播する 性質。

  1. セキュリティチーム(CCoE 内)が org-security-baseline.md に新しい項目を追加したいと考える
  2. 中央 Repo に PR を作成、CODEOWNERS で指定されたレビュアー(セキュリティチーム)がレビュー
  3. 必要に応じて他の関連チームにも PR を共有(ランタイムチーム、CCoE の総合判断)
  4. 合意形成後 merge
  5. 各事業部の開発者が次回 dotkiro update を実行した時点で、更新が反映される
  6. 各プロジェクトの Kiro が、次回の spec 生成・コード生成からその新しい標準を参照するようになる

Slack や社内 Wiki で「標準更新したので各自更新してください」を流す運用に比べて、以下が優れている。

  • 到達漏れがない: dotkiro update を叩けば必ず最新が入る
  • 更新内容が Git diff として明示: 「何が変わったか」が PR で説明され、コミット履歴に残る
  • 承認プロセスが Git 上に残る: 誰がレビュー・承認したかが監査対象として使える
  • 破壊的変更時のロールバック容易: ブランチで v1 を維持すれば、既存プロジェクトは pin したまま

3.4 CI で整合性を担保する

プロジェクトの CI パイプラインに dotkiro init を組み込んでおくと、PR ビルド時に、最新の組織標準が適用された状態で Kiro が動く ことを保証できる。

# .github/workflows/kiro-check.yml(GitHub Actions の例)
- name: Sync Kiro conventions
  run: |
    npm install -g dotkiro  # 実際は git clone + npm link になる(後述)
    dotkiro init

さらに、CI 側で「.kiro/steering/ 配下のファイルと中央 Repo の内容が一致しているか」をチェックすれば、ローカルでの手動編集による標準逸脱を検出 できる。

4. CCoE(標準を配る側)のメリット

標準を作って配る CCoE から見た dotkiro の価値は以下に集約される。

4.1 配布の摩擦がなくなる

従来の「Slack で更新を告知 → 各チームが手動で反映」の運用は、到達率と反映率が本質的に担保できない。dotkiro では配布経路が git clone + dotkiro update に集約されるため、CCoE 側の告知コストが大幅に減る。

4.2 変更管理が Git / PR に一本化される

組織標準の変更が Pull Request として残る。これにより:

  • いつ・誰が・何を変更したかが恒久的に追跡可能
  • 議論・合意形成プロセスも PR コメントとして残る
  • 監査対応時に「この標準の承認プロセスは?」に即座に答えられる

Confluence ベースの運用では、ドキュメントの版管理は手動に依存し、変更履歴が散逸しがち。PR ベース運用はこれを構造的に解消する。

4.3 CODEOWNERS で所管が明確化される

中央 Repo の CODEOWNERS ファイルで、「セキュリティベースラインの変更はセキュリティチームの承認が必須」「Lambda 標準はランタイムチームが所有」のようにパスごとの所管を明示できる。

# CODEOWNERS の例
/steering/org-security-baseline.md      @org/security-team
/steering/org-iam-minimum-permissions.md @org/security-team
/lambda/                                 @org/runtime-team
/cdk/                                    @org/iac-team
/regulated/                              @org/compliance-team @org/security-team

事業部からの質問・変更依頼が、GitHub の PR / Issue で所管チームに自動ルーティングされる。CCoE 内の分業が明確になる。

4.4 破壊的変更を安全に出せる

ブランチベースのバージョニング(main / v1 / v2)で、既存プロジェクトに影響を出さずに新しい標準を導入できる

  • 破壊的変更を含むリリースは新しいブランチで
  • 事業部は準備ができたタイミングで .dotkirorcbranch を切り替える
  • CCoE は旧ブランチを一定期間メンテすることで移行猶予期間を提供できる

これは Confluence 管理では実現困難な「バージョン並行運用」をクリーンに実現する。

4.5 標準逸脱を検出・追跡できる

CI で「プロジェクトの .kiro/steering/ が中央 Repo と一致しているか」をチェックする仕組みを入れれば、ローカル編集による標準逸脱を検出できる。検出された逸脱は以下の観点で分析できる。

  • 意図的な逸脱 → 標準自体への改善提案として吸い上げる
  • 意図しない逸脱 → 教育不足や運用上の問題として改善する

4.6 標準の利用状況が(将来的に)可視化できる

中央 Repo への git clone / git fetch のアクセスログを解析すれば、どの types がどの頻度で使われているかが概算把握できる。CCoE としての投資対効果(ROI)を示す根拠にもなる。

5. 事業部(標準を使う側)のメリット

標準を受け取って使う事業部開発者から見た dotkiro の価値。

5.1 新規プロジェクトのオンボーディングが短縮される

従来の「Confluence で標準を探す → 読み解く → 各ファイルをコピー&ペースト → PR Review で指摘されて修正」というサイクルが、.dotkirorc のコミットと dotkiro init の 2 ステップ に置き換わる。

新メンバーが参加した時も:

git clone <project-repo>
cd <project>
dotkiro init

これだけで、そのプロジェクトで想定されている組織標準が即時に手元に揃う。プロジェクト個別の設定が記録済み(.dotkirorctypes 指定)なので、「このプロジェクトでは何を使うのか」を新人が調べる手間も省ける。

5.2 組織標準の最新版が常に自動で届く

dotkiro update を実行すれば、Slack や社内 Wiki を追わなくても 最新の標準が手元に来る。CI で定期実行すれば、意識せず最新化される。

標準変更の内容は差分として見えるので、自分のプロジェクトに何が反映されたかを git diff .kiro/ で即座に確認できる。

5.3 自作 steering と組織標準が共存できる

dotkiro は manifest で管理しているファイルのみを触る 設計なので、事業部独自の steering を .kiro/steering/ 配下に追加しても、dotkiro update で上書き・削除されない。

.kiro/steering/
  ├── org-security-baseline.md         ← dotkiro 管理(中央 Repo)
  ├── org-iam-minimum-permissions.md   ← dotkiro 管理
  ├── lambda/
  │   └── lambda-runtime-standard.md   ← dotkiro 管理
  └── project-specific-rule.md         ← 事業部が追加、触られない

「組織標準を受け入れつつ、プロジェクト固有の要件は自分で追加できる」 という柔軟性が担保される。事業部は CCoE の標準と戦わずに済む。

5.4 必要な types だけ取得できる

.dotkirorctypes 配列で、このプロジェクトに必要な標準だけを取得できる。不要な複雑性を持ち込まずに済む。

  • Lambda プロジェクトなら lambda のみ
  • 規制業界の CDK プロジェクトなら cdk + regulated
  • バッチ処理なら ecs + batch

「関係ないセクションの記述が長すぎて読まない」という問題を、必要な範囲に限定することで回避する。

5.5 監査・コードレビュー時の説明責任が楽になる

「この設計は組織標準のどこに準拠しているか」を問われた際、.kiro/steering/ の該当 .md ファイル + dotkiro の manifest を見せれば根拠が示せる。

  • 中央 Repo の特定コミット → このプロジェクトに反映されたコミット、の追跡が可能
  • CODEOWNERS で承認者が明確なので、標準自体の出所を辿れる
  • 監査対応で「あなたのプロジェクトで使用した標準のバージョンは?」に即座に答えられる

5.6 Kiro の出力品質が底上げされる

これは地味だが大きい。組織のベストプラクティスが必ず Kiro のコンテキストに入るので、Kiro が生成するコード・spec・レビューコメントの品質が、事業部固有の教育コストをかけずに引き上がる。

経験豊富なエンジニアが書いた steering が、新人を含む全員の Kiro セッションに反映される。これは事業部にとって「CCoE のエンジニア品質が全員に薄く広がる」効果がある。

6. 展開 KPI

dotkiro を使った展開が効いているかを測る指標。CCoE が継続的に観測すべきもの。

  • 新規プロジェクトのオンボーディング時間: dotkiro init 後、初回 /quick-spec が走るまでの時間
  • 標準更新の伝播時間: 中央 Repo の merge から、全事業部プロジェクトが dotkiro update を実行するまでの時間
  • 標準逸脱率: CI で検出した、ローカル編集による標準との差分の件数
  • 新規 types 追加のリードタイム: 新しい type(例: bedrock)を中央 Repo に PR → 事業部利用開始までの時間
  • CODEOWNERS レビュー応答時間: 各 type の所管チームが PR レビューに応答するまでの時間
  • 事業部からの標準改善提案件数: 事業部側からの PR / Issue 提出数(標準が「生きている」指標)

これらを継続観測することで、CCoE としての標準配布の運用品質を改善できる。

7. 導入時の考慮点

7.1 Labs プロジェクトゆえの公式サポートなし

前回記事「Kiro のエコシステムを整理する」で触れたとおり、Labs プロジェクトは公式 kirodotdev Org とは分離された位置付けになっている。

業務利用時の評価観点:

  • ステータス確認(Active / Maintenance / Archived
  • メンテナーの応答性(Issue / PR の対応履歴)
  • 万が一メンテ停止した場合の乗り換え計画(fork or 自前実装)
  • セキュリティ更新の通知チャネル

7.2 npm 公開されていない、インストール動線の摩擦

執筆時点で dotkiro は npm registry に公開されていないので、インストールは git clone + npm link になる。

git clone https://github.com/kirodotdev-labs/dotkiro.git
cd dotkiro
npm link

エンタープライズ環境では、以下で摩擦が減る。

  • 社内 npm レジストリへの publish(Verdaccio / JFrog Artifactory / AWS CodeArtifact)
  • 社内 Chocolatey / Homebrew tap での配布
  • 開発者 PC セットアップ script に同梱

業務利用時は、開発者 1 人 1 人に git clone + npm link を求めず、社内配布経路を整備する運用が現実的。

7.3 ブランチ戦略

中央 Repo のブランチ戦略は慎重に設計する。

  • main = 現在の推奨標準(機能追加・非破壊変更)
  • v1, v2, ... = メジャーバージョン(破壊的変更の分岐点)
  • Git tag で特定リリースを pin する運用も可能(--branch=v2.3.0

事業部プロジェクトの .dotkirorc には、明示的にブランチを指定する 運用を推奨する。main を pin すると、想定外のタイミングで変更が入ってくる。

7.4 中央 Repo のアクセス制御

中央 Repo を private にする場合、dotkiro は内部で git clone するので、各開発者 PC と CI で Git 認証が通っている必要がある。以下を整備しておく。

  • SSH 鍵 / Personal Access Token / SSO 認証
  • CI 用の deploy key
  • 外部ベンダーに渡す場合の read-only アカウント

7.5 セキュリティ: 中央 Repo の改竄リスク

  • 中央 Repo への push は必ず PR 経由、直接 push 禁止(branch protection rules)
  • CODEOWNERS による必須レビュー
  • 重要 steering(セキュリティベースラインなど)は複数人レビュー必須
  • 監査ログ(誰がいつ merge したか)の保全
  • GitHub Actions などによる自動 lint(禁止ワード、フォーマット、疑わしいパターン)
  • 2FA / Hardware Security Key の強制
  • Merge 権限を持つアカウントの定期レビュー

これは dotkiro 固有の話ではなく、組織の標準リファレンス構成を Git で配布する以上、普遍的に必要な統制である。

8. /quick-spec × dotkiro の組み合わせ

前回までの記事で述べた話を統合すると、Kiro を使った組織標準化の全体像はこうなる。

┌──────────────────────────────────────────────────┐
│ CCoE が中央 Repo で steering / skills を管理        │
│ (lambda / cdk / regulated / ... の types で分類)  │
└──────────────────────┬───────────────────────────┘
                       │ dotkiro init / update

┌──────────────────────────────────────────────────┐
│ 事業部プロジェクトの .kiro/steering/, skills/        │
│ に組織標準が自動展開                                 │
└──────────────────────┬───────────────────────────┘
                       │ /quick-spec

┌──────────────────────────────────────────────────┐
│ 組織標準に沿った requirements.md / design.md /      │
│ tasks.md が生成される                              │
└──────────────────────────────────────────────────┘
  • dotkiro が「どう配るか」を担う
  • /quick-spec が「どう使うか」を担う
  • steering / skills が「何を配るか」の中身

この 3 つが揃って、初めて標準リファレンス構成が組織スケールで機能する。

まとめ

  • Kiro の steering / skills を 書く 仕組みは揃っているが、配る 仕組みがないと形骸化する
  • dotkiro は「中央 Git リポジトリ + CLI + manifest」の組み合わせで、標準の配布・更新・追跡を一手に引き受ける
  • CCoE 側は、配布の摩擦削減・変更管理の Git 一本化・CODEOWNERS による所管明確化・破壊的変更の安全な導入・逸脱検出など、運用品質が構造的に改善する
  • 事業部側は、オンボーディング短縮・最新標準の自動取得・自作 steering との共存・必要な types だけ取得・監査対応の容易化・Kiro 出力品質の底上げなど、日常の開発体験が底上げされる
  • types 概念で shared + 言語別 + チーム別 + 業界別の多層化が可能、標準リファレンス構成のパターンに自然に適合
  • PR ベースの変更管理・ブランチによるバージョニング・CI 統合により、標準更新が組織横断に安全に伝播する
  • Labs プロジェクトで公式サポート外という制約はあるものの、組織標準配布の参照実装 として学ぶ価値は高い

CCoE として Kiro 運用を組織スケールで回す段階に入っているなら、dotkiro は 試作 → 評価 → 自社要件に応じた fork or 置換 という順で検討する価値がある。公式の代替手段が現れるまでは、このパターンの参照実装として機能する。

参考リンク

dotkiro 関連

筆者の関連記事

Discussion