Platform Architect

Platform Architect

核心コンセプト: "暗黙知の明示化、人間+AI二重可読、長期運用"

Platform Architecture（Layer 1）の構築・メンテナンスを担当するスキル。 全機能に適用される共通アーキテクチャ制約を体系的に文書化する。

役割分界

位置付け: ユーザー直接呼び出し（パイプライン外の独立スキル）

Two-Layer Architecture
│
├── Layer 1: Platform Architecture ← ★ このスキルが管理
│   ├── PADR-*.md (Platform ADR)
│   ├── constraints.json (機械可読制約)
│   ├── PLATFORM-ARCHITECTURE.md (Arc42ベース)
│   ├── tech-radar.md (ThoughtWorks形式)
│   ├── c4/platform-c4.md (C4 Level 1-2)
│   └── cross-cutting/ (横断的関心事)
│
└── Layer 2: Feature Architecture ← architecture-selector が管理
    └── docs/features/<id>/ADR-<id>.md

Architecture Contract Pattern:

• PADR-*.md: Why/Context（人間可読）
• constraints.json: What/Must/Must-Not（AI/機械可読）

プロトコル (Protocol) - 5フェーズ

Phase 1: Inventory（棚卸し）

既存文書からアーキテクチャ決定を収集する。

入力文書（優先順位順）:

1. CLAUDE.md - プロジェクトガイドライン、ルール
2. docs/technical/tech-stack-rules.md - 技術スタック詳細
3. docs/technical/feature-first-architecture.md - アーキテクチャガイド
4. docs/development/enhanced-pipeline-proposal.md - パイプライン提案（Appendix B）

抽出対象:

• 暗黙的に決定されているが ADR化されていないアーキテクチャ決定
• 技術スタックの選定理由（なぜその技術を選んだか）
• 制約（Must / Must-Not）
• 品質属性の優先順位

出力: 暗黙決定リスト（ID、カテゴリ、決定内容、出典文書）

Phase 2: PADR Generation（Platform ADR 生成）

各暗黙決定を Nygard 形式 PADR として文書化する。

PADR 構造:

# PADR-NNN: {タイトル}

## Status

Accepted (遡及作成: YYYY-MM-DD)

## Context

{決定が必要だった背景}

## Architecture Drivers

### Functional Drivers

### Quality Attribute Drivers

### Technical Constraints

### Business Constraints

## Alternatives Considered

### Option A: {名前}（採用）

### Option B: {名前}（不採用）

### Option C: {名前}（不採用）

## ATAM Lite Evaluation

| Quality Attribute | Weight | Option A | Option B | Option C |
|...

## Decision

Option A を選択する。{根拠}

## Consequences

### Positive

### Negative

### Risks

## Rules（制約）

- Must: ...
- Must Not: ...

## References

命名規則:

• 接頭辞: PADR-NNN（Feature ADR の ADR-<feature_id> と区別）
• 配置: docs/architecture/adr/
• ステータス: Accepted（遡及作成のため）

Phase 3: Contract Generation（constraints.json 生成）

PADR から constraints.json（機械可読制約）を自動生成する。

スキーマ: references/constraints-schema.json

各 constraint の構造:

{
  "id": "PC-NNN",
  "source_padr": "PADR-NNN",
  "category": "architecture|state_management|backend|data_model|...",
  "rule": "ルール名",
  "description": "説明",
  "must": ["必須事項1", "必須事項2"],
  "must_not": ["禁止事項1", "禁止事項2"],
  "applies_to": ["glob パターン"],
  "override_allowed": false,
  "enforcement": "critical|high|medium"
}

生成ルール:

• 各 PADR の Rules（制約） セクションから Must/Must-Not を抽出
• applies_to は影響範囲のファイルグロブパターン
• enforcement は品質属性の Weight から決定（H→critical, M→high, L→medium）

Phase 4: Platform Doc Generation（PLATFORM-ARCHITECTURE.md 生成）

Arc42 ベース 10 セクション構成のプラットフォーム全体像文書を生成する。

テンプレート: references/platform-architecture-template.md

付随ファイル:

• tech-radar.md - ThoughtWorks Tech Radar 形式
• c4/platform-c4.md - Mermaid C4 Level 1-2
• cross-cutting/*.md - エラーハンドリング、ログ、セキュリティ

Phase 5: Verification（検証）

constraints.json ↔ PADR 整合性チェック。

検証項目:

出力: 検証結果レポート（Pass/Fail + 詳細）

Model Routing

AI 行動指針

DO（すべきこと）

• ✅ 既存文書（CLAUDE.md, tech-stack-rules.md）を忠実にPADR化する
• ✅ 各PADRに最低3つの代替案を含める
• ✅ constraints.json のスキーマを厳密に守る
• ✅ PADR と constraints.json の整合性を検証する
• ✅ 業界標準（Arc42, ATAM, Tech Radar）に準拠する
• ✅ Two-Layer Architecture の分離を維持する（Platform vs Feature）
• ✅ deviation_policy を明文化する

DON'T（してはいけないこと）

• ❌ Feature-level の決定を Platform ADR に含めない
• ❌ constraints.json に PADR にない制約を追加しない
• ❌ 既存の CLAUDE.md ルールと矛盾する PADR を作成しない
• ❌ ATAM Lite 評価なしに決定を記録しない
• ❌ 検証（Phase 5）をスキップしない

出力ファイル

使用例

# 初回構築（全Phase実行）
/platform-architect

# 特定フェーズのみ実行
/platform-architect --phase inventory
/platform-architect --phase verify

# 新技術追加時の更新
/platform-architect --update "新技術名の追加"

実行タイミング

参照文書

• constraints.json スキーマ - 機械可読制約のJSONスキーマ
• Platform Architecture テンプレート - Arc42テンプレート
• architecture-selector スキル - Feature-level ADR（Layer 2）
• feature-pilot スキル - パイプラインオーケストレータ
• enhanced-pipeline-proposal.md - Appendix B