orchestration-workflow

オーケストレーションワークフロー

最適化サイクル

1. ANALYZE    -> Read devlog overview + current best results
2. PROFILE    -> Launch Profiler Agent -> get compact bottleneck analysis
3. SELECT     -> Choose implementation language based on the required control level
4. STRATEGIZE -> Load the shared optimization guidance plus the language-specific optimization catalog
5. DESIGN     -> Launch Kernel Designer Agent -> implement optimizations in new version
6. VERIFY     -> Launch Profiler Agent on new version -> compare with previous
7. EVALUATE   -> Target met? -> Done. Not met? -> Back to step 3
8. LEARN      -> If novel insight: update knowledge base (mandatory)

プロファイリングまたは実装の反復によって、再利用可能なパターン、適用条件の改良、あるいは以前の想定の誤りが明らかになった場合は、必ず LEARN のステップを実行してください。

---

デフォルト設定

投機的デコーディング

b=32, s=16, t=4096 -- OOM が発生する場合は b を小さくしてください。

探索的なチューニングにおけるデフォルトの試行マトリックス

• デコード系：b=32, s=1, t=4096
• 投機系：b=32, s=16, t=4096
• 最初の 2 つの設定では不十分であることが、戦略または devlog の証拠から示された場合に限り、3 つ目のストレス設定を追加してください。

チューニング空間の探索

• まず、良好な結果が期待できる手動のタイル設定をテストします。
• いくつかのタイル設定を調べ、タイルサイズによってパフォーマンスがどのように変化するかを把握します。
• 状況が複雑な場合は、良好な設定を見つけるために大まかな自動チューニングを検討します。ただし、組み合わせの爆発に注意し、ドメイン知識を用いて探索空間を絞り込んでください。カーネル設計の探索を高速に保てるよう、自動チューニングにかかる時間は十分に短くする必要があります（例：カーネルバージョンごとに 1 時間未満）。
• カーネルバージョンに大きな可能性が見られる場合は、パフォーマンスをさらに改善するため、より細かい自動チューニングを検討します。そうでなければ、次の最適化の反復に進んでください（十分な見込みのないカーネルバージョンの自動チューニングに時間をかけすぎないでください）。

たとえば、mla_var6_plus_v3 は悪い例です。自動チューニングの設定が 10'000 個あるにもかかわらず、mla_var6_plus_v2 に対して有意な改善がありません。自動チューニングよりもカーネル設計のほうが重要です。

---

サブエージェント起動テンプレート

エージェントの定義は .claude/agents/ にあります。タスクプロンプトを指定して、名前でエージェントを起動してください。

プロファイラー

タスクプロンプトを指定して、profiler エージェントを起動します。

Profile <kernel> <version> at b=X, s=X, t=X.
Return compact summary per the output contract.
Update the devlog performance section in docs/kernels/<kernel>.md.

プロファイラーには、エージェント定義を通じて /profile-kernel があらかじめ読み込まれています。

カーネル設計者

タスクプロンプトを指定して、kernel-designer エージェントを起動します。

Create <kernel> <new_version> from <current_version>.
Language: <cutile-dsl|cute-dsl>.
Load /design-<language>-kernel and the matching reference skill if one exists.
Apply optimizations: [specific list with rationale].
Return implementation summary per the output contract.

カーネル設計者には /design-kernel があらかじめ読み込まれています。使用言語はオーケストレーターの選択によって異なるため、言語固有のスキルは引き続き必要に応じて読み込む必要があります。

---

エージェント間の連携契約

プロファイラー -> オーケストレーター（簡潔な出力）

## Profile: [kernel] [version] | b=X, s=X, t=X
### Stages
| Stage | Duration | TC% | DRAM% | Occ% | Bottleneck | Key Issue |
### Bottleneck: [Memory/Compute/Latency]-bound
Root cause: [2 sentences]
### Top 3 Opportunities (ranked by estimated impact)
1. [name] -- est. X% gain -- trigger: [metric=value]

### vs Baseline (if applicable)
| Metric | Previous | Current | Change |
|--------|----------|---------|--------|

オーケストレーター -> 設計者（指示）

## Optimization Task: [kernel] [current] -> [new_version]
### Current Bottleneck: [from profiler]
### Optimizations to Apply:
1. [specific optimization + rationale + link to the shared or language-specific knowledge file]

### Constraints
- register budget, target occupancy, required control level, and language-specific constraints

設計者 -> オーケストレーター（要約）

## New Version: [kernel] [version]
### Changes Applied: [list]
### Files: Created/Modified [paths]
### Correctness: [PASS/FAIL]

### Trial Configurations Checked
1. [b, s, t] -- [why this point matters]

### Devlog Entry Written: [path]

---

ナレッジベース更新プロトコル

更新するタイミング

• カーネルのプロファイリング後、カタログにまだない新たな有用な最適化またはアンチパターンが特定された場合
• カーネルのプロファイリング後、既存の最適化またはアンチパターンが誤りであると判明し、その有効条件の更新、または必要に応じてアンチパターン／最適化への変更が必要な場合
• 新たなパフォーマンスの証拠によって、最適化の推定効果またはアンチパターンの失敗モードが精緻化された場合
• 最適化間の新たな相互作用が見つかった場合
• デバイス固有の結果を再利用可能なルールとして抽象化できる場合

新しい最適化が検証された場合

1. 発見した内容が、共有されるアルゴリズム／ハードウェアの知識なのか、言語固有の実装知識なのかを判断します。
2. 共有される知識は docs/knowledge/optimizations/<name>.md に記載します。
3. 言語固有の知識は docs/knowledge/languages/<language>/optimizations/<name>.md に記載します。
4. /optimization-catalog スキルの最適化インデックスに、対応する行を追加します。
5. 再利用可能なパターン、適用条件、および主に影響するメトリクスを記録します。
6. ローカルな証拠と一般化した内容を明確に分けます。

最適化によって明確な性能低下が発生した場合

1. 障害のパターンが共通のものか、特定の言語に固有のものかを判断します。
2. 共通のアンチパターンは docs/knowledge/anti-patterns/<name>.md に記載します。
3. 言語固有のアンチパターンは docs/knowledge/languages/<language>/anti-patterns/<name>.md に記載します。
4. /optimization-catalog スキルのアンチパターンインデックスに、対応する行を追加します。
5. 障害のパターンは、失敗したカーネルやバージョンだけに限定せず、再利用できる形で記録します。
6. 問題を明らかにしたメトリクスと、問題が発生する状況を記録します。

詳細ファイルのテンプレート

すべての最適化とアンチパターンでは、適用対象となる状況（例：MLA 固有、あらゆるオンライン softmax カーネル、特定のパターンを持つカーネル）を明確に示す必要があります。この状況は When to Apply セクションに記載します。

# [Optimization Name]

## When to Apply
- [Context 1: e.g., specific kernel design or reference layer/kernel]
- [Context 2]
- [Metric condition 1]
- [Metric condition 2]

## Mechanism
[How and why this optimization works]

## Affected Metrics
- [Metric 1: e.g. occupancy]
- [Metric 2: e.g. registers/thread]
- [Metric 3: e.g. Tensor Core utilization, DRAM throughput, L2 hit rate, local-memory traffic]

## Implementation
\`\`\`python
# Code snippet
\`\`\`

## Performance Evidence
Source type: [local experiment / external report]
| Config | Before | After | Change |
|--------|--------|-------|--------|

## Generalization
[Device-agnostic takeaway. Mention architecture/device facts only insofar as they sharpen the reusable rule.]

## Pitfalls
- [Known failure modes]

## Interactions
- [How this interacts with other optimizations]