HN 日本語サマリー

← 一覧へ戻る
プログラミング

Claude CodeとCodexにチームのコーディング標準をもたらすエージェントスキル

Agent skills that bring team coding standards to Claude Code and Codex (github.com)

5 pointsby kanfilior0 コメント

要約

この記事は、エンジニアリングチームがAIエージェントを統合し、共有されたコーディング標準とチームの指示を強制するためのオープンソースプロジェクト、ADLC Team Skillsを紹介しています。バージョン管理されたチームのコンテキストモジュール、ルール、スキルのリポジトリを通じてAIエージェントを管理し、個々の「バイブコーディング」を超えて、混沌とした技術的負債やコンテキストの陳腐化を防ぐことを目指しています。このシステムは、AIエンジニアリングにおける信頼と検証のボトルネックを解消し、チーム全体の生産性とコード品質の向上を支援します。

全文翻訳

adlc-team-skills

セッション開始時にチームのコンテキストをコーディングエージェントに与え、見知らぬ人としてではなくチームの一員として機能させるエージェントスキル。

目次

仕組み

セッションを開いた瞬間から始まります。team-bootはsession_startイベントフックを介して起動し、チームのルールを軽量なインデックス(名前と1行の説明文で約100トークン)を注入します。ルールそのものではありません。アクティブなタスクがルールに一致すると、エージェントはオンデマンドでそのルールのフルテキストを取得します。SQLを扱うタスクはSQLルールをロードし、それ以外のタスクは何もロードしません。

インデックスはGitリポジトリ(team-ai-directives)に格納され、バージョン管理され、PRによってレビューされ、チーム全体で共有されます。もう、1台のマシンにしか存在せず、古くなり、チームメイトやツール間で転送されない個人的なCLAUDE.mdファイルはありません。

エージェントに何かを構築するように依頼しても、すぐにコードに飛びつくわけではありません。factory-missionはまず契約(目標、制約、非目標、成功基準 - ミッションブリーフ形式)を強制し、その後specify → plan → implement ↔ convergeのプロセスを、ゲート、サーキットブレーカー、再開機能、監査証跡とともに実行します。セッション中に苦労して得た修正が見つかった場合、team-levelupはその修正をコンテキストディレクティブレコード(CDR)として抽出し、信頼度でスコアリングし、承認されたCDRをチームリポジトリに公開します。使用データと信頼度スコアはadlcオーファンブランチに格納され、次のセッションはより賢く開始され、CDRは実際の使用状況に基づいてランク付けされます。

検証、履歴、技術選定にはそれぞれ独自のループがあります。ルールやスキルの動作の証明が必要な場合、evals-*スキルは実行可能なグレーダー(コードが検証できるバイナリチェック、静的チェックでは不可能なもののみLLMが判断)を構築し、ホールドアウトスプリットとTPR/TNRで検証します。古いコードに触れて、なぜこのようになっているのか疑問に思った場合、change-initはGit履歴から問題に関連付けられたコミットをマイニングし、過去の変更の根拠をChDRとして復元します。そして、技術選択の機会が生じた場合、tech-radar-bootは選択がADRとしてキャプチャされる前に、Tikal Tech Radarの意見(採用リング、象限)を注入します。

そのセッションループは、より大きなループ、つまりソフトウェアファクトリの中にあります。factory-queueは受信した作業をトリアージし、factory-missionはそれを仕様でゲートされたミッションとして分離されたワークツリーで実行し、factory-reviewは結果のPRをポリシー・アズ・コードに対して採点し、factory-learnは実行から学んだことをチームAIディレクティブにフィードバックします。各意思決定ポイントには人間のゲート(⭐)があります。1つのプラットフォーム:インテーク → ミッション → レビュー → 学習。

そして、スキルはインデックスから自動的にトリガーされるため、インストール後は特別なことをする必要はありません。あなたのコーディングエージェントは、あなたのチームのコンテキストを持っているだけです。

開発者のジャーニー

ゼロからファクトリまで、順を追って実際にどのように進むか。

0. 前提条件
  • コーディングエージェント(opencode, Claude Code, Cursor, Codex, Gemini CLIなど)
  • adlc-cli — npxで動作し、インストール不要
  • jq — team-bootスクリプトがディレクティブインデックスをこれで解析します
1. インストール — プロジェクトごとに1コマンド
npx adlc-cli team setup tikalk/adlc-team-skills -a opencode

これにより、スキル(npx skills add経由)、/nameスラッシュコマンド、イベントフックがインストールされ、その後/team-setupがヘッドレスで実行され、チームAIディレクティブのリポジトリをクローン、リンク、またはスキャフォールドします。これにより、後続のすべてのコマンドがどこに何があるかを知るために.adlc/init-options.json(エージェント、スキルソース、ディレクティブパス)が書き込まれます。

単にnpx adlc-cli skills add tikalk/adlc-team-skills -a <agent>を実行すると、チーム設定なしでスキル+コマンド+イベントがインストールされます。

2. 初回セッション — コンテキストは自動的に到着します

プロジェクトでセッションを開きます。team-bootはsession_startで起動し、インデックス(憲法タイトル、信頼度でランク付けされたCDRインデックス、クラスブートカタログ、スキルレジストリ、MCPサーバー)を注入します。未設定のプロジェクトでは/team-setupに誘導されます。/team-constitutionでチームの原則が一度入力されます。この時点以降、覚えることは何もありません — スキルはタスクが一致したときにトリガーされます。

3. 日々の作業 — インデックス、クラスブート、意思決定のキャプチャ
  • エージェントは、あらゆるタスクの前にディレクティブインデックスをチェックします。フルルールボディはオンデマンドでロードされます。
  • クラスブートは、意思決定クラスが表示されたときに起動します:architect-boot(ADRインデックス)、product-boot(PDRインデックス)、change-boot(ChDRインデックス)、tech-radar-boot(技術選択前のレーダー意見)。
  • 意思決定キャプチャは継続的に実行されます:セッション中に検出された意思決定は、.adlc/drafts/{adr,pdr,chdr,cdr,evals}/に軽量なドラフトとして着地します。file_editedフックは各ドラフトの着地を検知し、対応する明確化スキル(adr→/architect-clarify、pdr→/product-clarifyなど)を促します。
  • ハーネスの圧縮が履歴を要約して削除した場合、session_compactがインデックスを再注入します。
4. セッション終了 — 学習がレコードになる

team-levelupはsession_endで起動します:苦労して得た修正をCDR + ペアになった評価CDRとして抽出し、信頼度をスコアリングし、バッチレビューを行い、承認されたCDRをチームAIディレクティブへのドラフトPRとして公開します。ドラフトと使用レポートはadlcオーファンブランチ(drafts/cdr/ + reports/)に格納されます。

5. 個々のライフサイクル — オンデマンド

各レコードクラスには、明示的に呼び出す独自のスキルループがあります。

Product:     product-specify|init → product-clarify (accept + promote to memory) → product-implement → product-analyze
Architecture: architect-specify|init → architect-clarify (accept + promote to memory) → architect-implement → architect-analyze
Team:        team-init → team-levelup (extract + review + publish) → team-repair (--update-confidence)
Change:      change-init → change-clarify → change-publish (change-boot injects the chdr.md index)
Evals:       evals-init → evals-specify → evals-clarify → evals-implement → evals-validate

承認されると、受け入れられたPDR/ADRはメモリに昇格されます。「ドラフトで承認」と「メモリに移動」の間にギャップはありません。

6. ソフトウェアファクトリ — 外側のループ

インテーク → 実行 → レビュー → 学習を自動で実行しますか?ファクトリはキューからPRまで担当します — ソフトウェアファクトリを参照してください。

継続的なメンテナンス

adlc-cli team update     # git pull team-ai-directives + skills update + confidence update
adlc-cli team repair     # full repair via agent run (reindex, conflicts, freshness)
adlc-cli team repair --update-confidence  # deterministic confidence aggregation (no agent)

team-repair --build-to-deleteはルールなしで評価を再実行し、モデルがそれでもパスする場合は削除を提案します。--validate-draftsはドラフトファイルを変更せずに検証します。

これらのスキルが解決する問題

#問題解決策
1エージェントはチームの働き方を知らないteam-* — セッション開始時のインデックス + オンデマンドルール
2エージェントは尋ねる代わりに推測するfactory-mission — コードの前に仕様契約
3作成者が自身の作業を採点するevals-* — バイナリグレーダー、ホールドアウトスプリット、自動マージなし
4セッションの学習が蒸発するteam-levelup — 修正をCDRとして抽出し、チームリポジトリに公開
5製品およびアーキテクチャの決定が見えないproduct-* / architect-* — PDR→PRD、ADR→ADのトレーサビリティ
6「なぜこれが変更されたのか?」は考古学 — 根拠は誰も頭の中にないchange-* — Git履歴からマイニングされたChDR(問題に関連付けられたコミットから)
7エージェントはノリで技術を選ぶ、チームの意見ではないtech-radar-boot — ADRの前にレーダーコンテキスト(採用リング、象限)
8ルールが積み重なり腐敗するteam-repair --build-to-delete — ルールは増えるのではなく、減るべきです。機械的なルールは決定的なCIチェック(EVAL-010)に昇格されます
9承認された決定がドラフトに残ったまま、メモリにならないClarify-side promotion — 承認されたPDR/ADRは承認時にメモリに移動(アトミック)。sweep_duplicatesが残りをキャッチ。analyzeが重複をHIGHとしてフラグ付け

インストール

# 1コマンド: スキルをインストール + team-ai-directivesを設定(インタラクティブな/team-setupを実行)
npx adlc-cli team setup tikalk/adlc-team-skills -a opencode

# または単にスキルをインストール(team-setupなし)
npx adlc-cli skills add tikalk/adlc-team-skills -a opencode

# またはプレーンなスキル(コマンド/イベントなし)
npx skills add tikalk/adlc-team-skills -a claude -g

選択的なインストールは依存関係を自動的に解決します:--skill architect-implementは、その正規のホーム(architect-clarify)も.skills-deps.json経由でプルするため、共有ヘルパーは決して孤立しません。借りたスキルは、正規のホームが見つからない場合、正確なリカバリコマンドで迅速に失敗します。

Agent Skills標準をサポートする任意のエージェント(Claude Code, Codex, OpenCode, Cursor, Copilotなど)と連携します。

adlc-cliはnpx skills addをラップし、さらに/nameスラッシュコマンドを生成し、このリポジトリの.events.jsonで宣言された4つのイベントフック(session_startおよびsession_compact(team-boot)、session_end(team-levelup)、file_edited(team-boot、ドラフト書き込みの促し))を、ネイティブフックサポートを持つ9つのコーディングエージェントのために配線します。team setupは/team-setupスキルをagent run経由で実行し、チームAIディレクティブのリポジトリをクローン、リンク、またはスキャフォールドします。.events.jsonを持たないスキルリポジトリはコマンドのみを取得します。

初回実行: team-bootはセッション開始時に起動します。未設定のプロジェクトでは/team-setupに誘導され、チームAIディレクティブのリポジトリをクローン、リンク、またはスキャフォールドします。/team-constitutionで原則を入力します。

このリポジトリとagentic-sdlc-spec-kitを併用していますか? Spec Kitとの共存を参照して、競合のないインストールフローを確認してください。

ソフトウェアファクトリ

ファクトリスクリプトは、エージェント型SDLCの完全な外部ループです。これらは、ブラウンフィールドリポジトリをブートストラップからマージされたレビュー済みPRまで処理し、各実行で学んだことをチームメモリに変換します。自動化された各ステージは助言的なものであり、人間がゲート(⭐)を保持します。

 brownfield repo
        │
        ▼
┌─────────────────┐  統一ブートストラップ:製品 → アーキテクト → 変更
│  factory-init   │  追跡 + PDR↔ADR↔ChDR↔コードカバレッジマトリックス
└────────┬────────┘  (--refresh = 定期的なアライメントスイープ)
         │ PRD.md · AD.md · .adlc/memory/
         ▼
┌──────────────────────────┐  PDRs → PRD.md  ·  ADRs → AD.md
│ factory-product /        │  (clarify⭐ 人間ゲート)
│ factory-architect        │
└────────┬─────────────────┘
         │ ミッションブリーフ(目標 + 制約 + 成功基準)
         ▼
  インテントゲート ⭐ (人間がブリーフを承認。AIトリアージスコアは助言的)
         │
         ▼
┌─────────────────┐  トラッカーに仕様でゲートされたもの(Q、単一の真実の源)
│  factory-queue  │
└────────┬────────┘
         │ --issue ref
         ▼
┌─────────────────┐  内部ループ:指定 → 計画 → 実装 ↔ 収束
│ factory-mission │  (コメントバス · ワークツリー · TDDテスト/コード分割 · サーキットブレーカー)
└────────┬────────┘
         │ エージェント作成のPR
         ▼
┌─────────────────┐
│ factory-review  │──▶ マージゲート ⭐ (人間コードオーナーの承認)
└────────┬────────┘
         ▼
┌─────────────────┐  CDRs/ChDRs → team-ai-directives PR
│  factory-learn  │  ワークフローメモリ → memory.jsonl
└────────┬────────┘
         │
         └─▶ factory-missionへ戻る(メモリ)
             + team-boot (CDRインデックス — コンテキストループを閉じる)

各ステーションが追加するもの:

  • factory-setup — 1コマンドでリポジトリをイシュー・トラッカーに接続:プロバイダー選択(リモートからの検出、明示的、または既に設定済み)、.adlc/issues-provider.ymlを書き込み(認証情報は決して含めず、上書きしない)。
  • factory-init — 1コマンドで既存リポジトリをADLCにオンボードし、PDR↔ADR↔ChDR↔コードカバレッジマトリックス(定期的なアライメントスイープのための--refresh)を生成します。
  • factory-queue — ミッションブリーフの取り込み:AI支援の助言的トリアージスコアリング、インテントゲート、ゲートラベルのスタンプ、マイルストーン/エピックの生成。
  • factory-mission — 実行エンジン:仕様でゲートされた内部ループ(指定 → 計画 → 実装 ↔ 収束)、トラッカーに依存しない統合、エージェント間コメントバス、ワークツリー分離、リースベースのライブネス、停止検出、および必須のTDDテスト/コード分割(REDゲート + GREENゲート、プロンプトレベルだけでなくスキルレベルで強制)。
  • factory-review — POLICY-AS-CODEに対するPRコンプライアンスを深刻度でランク付け。エージェントPRのマージを監視し、自動マージはしない。--self-healは、メーカーチェッカー分離とサーキットブレーカーを備えた3サブエージェントの収束ループ(Review→Fix→Converge)を実行します。
  • factory-learn — チームAIディレクティブへのレトロスペクティブ:ビルド・トゥ・デリートのプルーニング、機械的ルールのプロモート・トゥ・チェック。
  • factory-product / factory-architect — PRD.mdおよびAD.mdをclarify⭐ゲートとともに維持するライフサイクルコーディネーター。
  • factory-tickets — トラッカーを横断する読み取り専用ワークリスト、次のアクション可能な移動で分類。
  • factory-clean — リソースインベントリと回収(承認ゲート付き)。

詳細な配線

flowchart LR
    FQ["factory-queue<br/>Ingestion & Triage"] ~~~ IG{"Intent Gate"}
    FP["factory-product<br/>Product Lifecycle"] ~~~ CG1{"clarify⭐ Gate"}
    FA["factory-architect<br/>Architecture Lifecycle"] ~~~ CG2{"clarify⭐ Gate"}
    FM["factory-mission<br/>Execution Engine"] ~~~ CB{"Circuit Breaker"}
    FR["factory-review<br/>PR Compliance"] ~~~ MG{"Merge Gate"}
    FL["factory-learn<br/>Learning Loop"] ~~~ CG3{"clarify⭐ Gate"}
    FC["factory-clean<br/>Resource Cleanup"] ~~~ UG{"Approval Gate"}
    FT["factory-tickets<br/>Read-Only Worklist"]
    FI["factory-init<br/>Brownfield Bootstrap"]

    TR[("Issue Tracker<br/>GitHub / GitLab / Linear / Jira")]
    TD[([team-ai-directives<br/>repo])]

    FQ -->|"spec-gated labels"| TR
    TR -->|"--issue ref"| FM
    FP -->|"PRD.md"| FQ
    FA -->|"AD.md"| FQ
    FM -->|"agent-authored PRs"| TR
    TR -->|"PR diff + checks"| FR
    FR -->|"twice-mistake rule"| FL
    FL -->|"memory.jsonl"| FM
    FL -->|"draft PR"| TD
    FC -.->|"reads state files"| FM
    FT -.->|"read-only"| TR
    FI -.->|"via product-* leaves"| FP
    FI -.->|"via architect-* leaves"| FA
    FI -.->|"via change-* leaves (one-time deep)"| FL

ロード中

ユニバーサルオーケストレーション

factory-missionは独自のプロプライエタリなエコシステムを強制しません。ミッション開始時に、インストールされているスキルのディレクトリをスキャンし、各SKILL.mdのフロントマターを読み込み、そのインベントリをサブエージェントに渡します — モデルは各ステップに合ったスキルを選択します。以下と連携します:

ソース例
mattpocock/skills/tdd, /grill-me, /code-review
addyosmani/agent-skills終了条件チェックリスト
superpowersワークフロースキル
spec-kit / agentic-sdlc-spec-kit / OpenSpecSDDコマンドフレームワーク
このリポジトリproduct-specify, architect-specify, evals-validate, team-levelup
あなた自身のSKILL.md標準に従うものなら何でも

内容物

8つのカテゴリにわたる44のスキル。

チームディレクティブ — すべてのセッション、すべてのユーザー
  • team-boot — セッション開始時のブートストラップ。常に関連性の高いレイヤー(憲法タイトル、信頼度でランク付けされたCDRインデックス、クラスブートカタログ、スキルレジストリ)を注入し、オンデマンドでクラスブートにディスパッチします。自動トリガー。session_compactのために再宣言され、インデックスがハーネス圧縮を生き残るようにします。また、CDRキャプチャのためのセッション終了時の摩擦トリガー、および対応する明確化スキルを提案するfile_editedドラフト書き込みの促しも起動します。
  • team-setup — チームAIディレクティブリポジトリのクローン、リンク、またはスキャフォールド。
  • team-constitution — チームの原則をインタラクティブに定義または変更します。
  • team-discover — 手動再スキャン。構造化されたマッチテーブル(/team-discover)。
  • team-repair — 再インデックス、競合スキャン、鮮度、--build-to-delete、--validate-drafts、決定論的強制カバレッジチェック。
  • team-skills — ディレクティブリポジトリからチームスキルを閲覧/インストールします。
  • team-diagnose — チームコンテキストが表示されない場合の証拠ベースの診断。チェーン(init-options → jq → boot.sh → アーティファクト同期)をウォークし、インジェクションサイドのバグをadlc-cliにルーティングします。
ソフトウェアファクトリ — 外側のループ
  • factory-init — 統一されたブラウンフィールドブートストラップ + PDR↔ADR↔ChDR↔コードカバレッジマトリックス(--refresh)。
  • factory-queue — キュー取り込み、AI助言的トリアージスコアリング、インテントゲート、マイルストーン生成。
  • factory-mission — 実行エンジン:トラッカーに依存しない、コメントバス、ワークツリー分離、必須TDD RED/GREENゲート(テストエージェントが最初に失敗するテストを書き、実装エージェントがそれをパスするコードを書く)、サーキットブレーカー。
  • factory-review — REVIEW.mdに対する深刻度ランク付けされたPRポリシーコンプライアンス。エージェントPRのマージを監視します。
  • factory-product / factory-architect — 製品/アーキテクチャライフサイクルコーディネーター。
  • factory-learn — チームAIディレクティブをターゲットとした継続的改善ループ:ビルド・トゥ・デリートのプルーニング、プロモート・トゥ・チェック(EVAL-010)機械的ルール用。
  • factory-tickets — トラッカーを横断する読み取り専用個人ワークリスト。
  • factory-clean — リソースインベントリと回収(承認ゲート付き)。
ミッション駆動開発
  • factory-mission — 収束ループ、サーキットブレーカー、再開機能(`factory-mission