musubix 3.6.0 → 3.7.3

package/docs/qiita/musubix-v3.6.0-fastrender-insights.md

@@ -0,0 +1,625 @@
+---
+title: 'MUSUBIX v3.6.0: Cursor FastRenderプロジェクトのソースコード分析から得られた知見を統合'
+tags:
+  - TypeScript
+  - AI
+  - AIエージェント
+  - ソフトウェア設計
+  - MUSUBIX
+private: false
+updated_at: '2026-01-23'
+id: null
+organization_url_name: null
+slide: false
+ignorePublish: false
+---
+
+# MUSUBIX v3.6.0: Cursor FastRenderプロジェクトのソースコード分析から得られた知見を統合
+
+## はじめに
+
+MUSUBIX v3.6.0では、**Cursor社のFastRenderプロジェクト**のソースコード分析から得られた知見を統合しました。FastRenderは「数百のAIエージェントを数週間にわたって協調動作させ、100万行以上のブラウザエンジンを構築する」という野心的な実験プロジェクトです。
+
+本記事では、FastRenderのAGENTS.mdやトリアージシステムの分析から抽出したベストプラクティスと、それをMUSUBIXにどのように統合したかを解説します。
+
+## 目次
+
+1. [FastRenderプロジェクトとは](#fastrenderプロジェクトとは)
+2. [分析から得られた主要な知見](#分析から得られた主要な知見)
+3. [MUSUBIX v3.6.0の新機能](#musubix-v360の新機能)
+4. [コンポーネント詳細](#コンポーネント詳細)
+5. [使用例](#使用例)
+6. [まとめ](#まとめ)
+
+---
+
+## FastRenderプロジェクトとは
+
+### 背景: 長時間稼働する自律型コーディング
+
+Cursor社は「[長時間稼働する自律型コーディングをスケールさせる](https://cursor.com/ja/blog/scaling-agents)」というブログ記事で、マルチエージェント協調の実験結果を公開しました。
+
+> 数週間にわたって、コーディングエージェントを自律的に稼働させる実験を行ってきました。私たちの目標は、通常は人間のチームが数か月かけて完了させるようなプロジェクトに対して、エージェント駆動のコーディングの最前線をどこまで押し広げられるかを見極めることです。
+
+### FastRender: ブラウザをゼロから構築
+
+FastRenderは、この実験の成果物として公開されたRust製ブラウザエンジンです。
+
+| 項目 | 値 |
+|-----|---|
+| **リポジトリ** | [wilsonzlin/fastrender](https://github.com/wilsonzlin/fastrender) |
+| **言語** | Rust 25.5%, HTML 66.1%, C 4.8% |
+| **コミット数** | 29,858+ |
+| **同時稼働エージェント** | 数百 |
+| **総トークン数** | 数兆 |
+
+### 学んだ教訓
+
+Cursorの実験から得られた主要な教訓:
+
+1. **階層がないとエージェントはリスクを避ける** - フラットな構造では難しいタスクを避け、小さな安全な変更だけを行う
+2. **プランナーとワーカーの分離が有効** - 役割を分けたパイプラインが協調の問題を解決
+3. **構造の適切なレベルが重要** - 少なすぎると衝突・重複、多すぎると脆弱
+4. **プロンプト設計が最重要** - ハーネスやモデルよりもプロンプトが重要
+
+---
+
+## 分析から得られた主要な知見
+
+### 1. 優先度ベースのトリアージシステム (P0-P5)
+
+FastRenderのAGENTS.mdとtriage.mdから抽出した優先度システム:
+
+| Priority | Category        | Description                                           |
+|----------|-----------------|-------------------------------------------------------|
+| P0       | Panics/crashes  | 本番コードでのパニックはP0バグ                         |
+| P1       | Timeouts/loops  | 5秒の厳格な予算内に収める                              |
+| P2       | Accuracy        | コンテンツ欠落、レイアウト/ペイントの誤り              |
+| P3       | Hotspots        | レンダリングやイテレーション速度をブロックする場合      |
+| P4       | Fidelity        | コア機能に影響しない軽微な視覚的改善                   |
+| P5       | Spec expansion  | ページセット精度/パフォーマンスに直接寄与する場合のみ   |
+
+
+**Rule**: P0-P2の問題が存在する間はP5にスキップしない。ポリッシュの前にクラッシュを修正する。
+
+### 2. 非交渉事項 (Non-Negotiables)
+
+FastRenderのAGENTS.mdから抽出:
+
+```markdown
+- **No page-specific hacks** - ホスト名/セレクタの特殊ケースやマジックナンバー禁止
+- **No deviating-spec behavior** - 互換性のショートカットとして仕様から逸脱しない
+- **No post-layout pixel nudging** - パイプラインをステージ化して維持
+- **No panics** - 本番コードでエラーをクリーンに返し、作業を制限
+- **JavaScript execution must be bounded** - 割り込み/タイムアウトをサポート
+```
+
+### 3. ワーカーの「完了」の定義
+
+FastRenderでは、ワーカータスクは以下のいずれかを生成した場合のみ「完了」:
+
+| Outcome | Evidence |
+|---------|----------|
+| タイムアウト→レンダリング | ステータス変更 |
+| 大幅な高速化 | total_ms低下 |
+| パニック/クラッシュ排除 | 回帰テスト追加 |
+| 正確性修正 | ページセットでの改善 |
+
+**重要**: 測定可能なデルタを示せない場合、完了ではない。
+
+### 4. リソース制限の徹底
+
+FastRenderのリソース管理:
+
+```bash
+# 時間制限: -k オプションで SIGKILL を確実に送信
+timeout -k 10 600 bash scripts/cargo_agent.sh ...
+
+# メモリ制限: cgroups または prlimit
+bash scripts/run_limited.sh --as 64G -- ...
+```
+
+**原則**: 制限を超えた場合、それは調査すべきバグであり、制限を引き上げるものではない。
+
+### 5. ワークストリーム管理
+
+FastRenderのワークストリーム分類:
+
+| Workstream | Owns | Does NOT own |
+|------------|------|--------------|
+| `capability_buildout` | CSS, レイアウトアルゴリズム | ページ固有の修正、ブラウザUI |
+| `pageset_page_loop` | 特定ページのE2E修正 | 汎用機能作業 |
+| `browser_chrome` | タブ、アドレスバー、ナビゲーション | ビジュアルデザイン |
+| `js_engine` | vm-js実行、GC、仕様準拠 | DOM、Web APIs |
+
+---
+
+## MUSUBIX v3.6.0の新機能
+
+FastRenderの分析から得られた知見を12の新コンポーネントとして実装しました。
+
+### 概要
+
+| 優先度 | コンポーネント | パッケージ | テスト数 | 対応する知見 |
+|-------|---------------|----------|---------|-------------|
+| **P0** | ExtendedQualityGate | workflow-engine | 18 | トリアージシステム |
+| **P0** | ExtendedQualityGateRunner | workflow-engine | 13 | バッチ実行 |
+| **P0** | ResourceLimiter | agent-orchestrator | 20 | リソース制限 |
+| **P0** | NonNegotiablesEngine | policy | 18 | 非交渉事項 |
+| **P1** | SingleStepEnforcer | agent-orchestrator | 17 | 1ステップ完了 |
+| **P1** | EvidenceLevelValidator | workflow-engine | 23 | エビデンス検証 |
+| **P2** | TriageEngine | workflow-engine | 23 | 優先度トリアージ |
+| **P2** | BalanceRuleEngine | policy | 25 | バランスルール |
+| **P3** | MetricsCollector | core | 21 | メトリクス収集 |
+| **P3** | PatternLearningDB | pattern-mcp | 23 | パターン学習 |
+| **P4** | WorkstreamManager | agent-orchestrator | 26 | ワークストリーム |
+| **P4** | TestPlacementValidator | codegraph | 26 | テスト配置 |
+
+**合計**: 253テスト (100%合格)
+
+---
+
+## コンポーネント詳細
+
+### P0: 必須品質ゲート
+
+#### ExtendedQualityGate
+
+FastRenderのトリアージシステムを品質ゲートとして実装:
+
+```typescript
+import {
+  createExtendedGate,
+  toStandardGate,
+  isEntryGate,
+  isExitGate,
+} from '@nahisaho/musubix-workflow-engine';
+
+// 拡張品質ゲート作成
+const gate = createExtendedGate({
+  id: 'GATE-P0-001',
+  name: 'No Panics Check',
+  phase: 'implementation',
+  timing: 'entry',  // フェーズ開始時に実行
+  priority: 0,      // P0: 最高優先度
+  check: async (ctx) => {
+    const hasPanics = await checkForPanics(ctx);
+    return {
+      passed: !hasPanics,
+      message: hasPanics ? 'Panic detected' : 'No panics',
+    };
+  },
+  services: {
+    triageEngine,
+    nonNegotiablesEngine,
+  },
+});
+
+// 標準ゲートに変換
+const standardGate = toStandardGate(gate);
+```
+
+#### ResourceLimiter
+
+FastRenderのリソース制限ポリシーを実装:
+
+```typescript
+import {
+  ResourceLimiter,
+  createResourceLimits,
+} from '@nahisaho/musubix-agent-orchestrator';
+
+// リソース制限設定
+const limits = createResourceLimits({
+  maxConcurrentTasks: 10,
+  maxMemoryMB: 4096,
+  maxExecutionTimeMs: 300000,  // 5分
+  windowSizeMs: 60000,         // 1分ウィンドウ
+});
+
+const limiter = new ResourceLimiter(limits);
+
+// 実行前チェック
+if (limiter.canExecute('workstream-1')) {
+  limiter.recordExecution('workstream-1', {
+    taskId: 'TSK-001',
+    memoryMB: 512,
+    durationMs: 10000,
+  });
+} else {
+  console.log('Resource exhausted, waiting...');
+}
+```
+
+#### NonNegotiablesEngine
+
+FastRenderの非交渉ルールを実装:
+
+```typescript
+import {
+  NonNegotiablesEngine,
+  createNonNegotiablesEngine,
+} from '@musubix/policy';
+
+const engine = createNonNegotiablesEngine();
+
+// 検証実行
+const result = await engine.validate({
+  code: sourceCode,
+  filePath: 'src/feature.ts',
+});
+
+if (!result.passed) {
+  for (const violation of result.violations) {
+    console.error(`[${violation.rule}] ${violation.message}`);
+  }
+}
+```
+
+**デフォルトルール**:
+- `no-tests-skip`: テストスキップ禁止
+- `no-security-bypass`: セキュリティバイパス禁止
+- `no-console-in-prod`: 本番環境でのconsole禁止
+- `no-any-type`: any型使用禁止
+- `no-hardcoded-secrets`: ハードコードされた機密情報禁止
+
+### P1: 高優先度
+
+#### SingleStepEnforcer
+
+FastRenderの「1タスク完了」原則を実装:
+
+```typescript
+import {
+  SingleStepEnforcer,
+  createStepDefinition,
+} from '@nahisaho/musubix-agent-orchestrator';
+
+const enforcer = new SingleStepEnforcer({
+  maxLinesPerStep: 100,
+  allowMultiFile: false,
+  requireTests: true,
+});
+
+const step = createStepDefinition({
+  name: 'Add validation',
+  files: ['src/validator.ts'],
+  linesChanged: 50,
+});
+
+// ステップ実行
+const result = await enforcer.enforceStep(step, async () => {
+  // 実装
+  return { success: true };
+});
+
+if (!result.valid) {
+  console.error('Step validation failed:', result.warnings);
+}
+```
+
+#### EvidenceLevelValidator
+
+FastRenderの「測定可能なデルタ」要件を実装:
+
+```typescript
+import {
+  EvidenceLevelValidator,
+  EvidenceLevel,
+} from '@nahisaho/musubix-workflow-engine';
+
+const validator = new EvidenceLevelValidator();
+
+// 検証
+const result = validator.validate({
+  phase: 'implementation',
+  evidence: {
+    testsAdded: 5,
+    testsPassing: 5,
+    coverageIncrease: 10.5,
+    performanceImprovement: null,
+  },
+});
+
+// 必要レベル取得
+const requiredLevel = validator.getRequiredLevel('implementation');
+// => EvidenceLevel.HIGH
+```
+
+### P2: 中優先度
+
+#### TriageEngine
+
+FastRenderのP0-P5優先度システムを実装:
+
+```typescript
+import {
+  TriageEngine,
+  createTriageEngine,
+} from '@nahisaho/musubix-workflow-engine';
+
+const engine = createTriageEngine();
+
+// タスクトリアージ
+const priority = engine.triage({
+  type: 'bug',
+  severity: 'critical',    // panic/crash
+  urgency: 'immediate',
+  impact: 'high',
+  blocksNewWork: true,
+});
+// => { priority: 0, label: 'P0', action: 'fix-immediately' }
+
+// ブロッキングチェック
+const isBlocking = engine.checkBlocking(priority);
+// => true (P0-P1はブロッキング)
+```
+
+#### BalanceRuleEngine
+
+コード変更のバランス評価:
+
+```typescript
+import {
+  BalanceRuleEngine,
+  createBalanceRuleEngine,
+} from '@musubix/policy';
+
+const engine = createBalanceRuleEngine();
+
+// 変更追加
+engine.addChange({ file: 'src/feature.ts', lines: 100, type: 'feature' });
+engine.addChange({ file: 'src/feature.test.ts', lines: 80, type: 'test' });
+
+// バランス評価
+const result = engine.evaluate();
+// => { passed: true, ratio: 0.8, message: 'Good test coverage' }
+
+// レポート生成
+const report = engine.getBalanceReport();
+```
+
+### P3: 低優先度
+
+#### MetricsCollector
+
+FastRenderのprogress/pages/*.jsonシステムを参考:
+
+```typescript
+import {
+  MetricsCollector,
+  createMetricsCollector,
+} from '@nahisaho/musubix-core';
+
+const collector = createMetricsCollector({
+  categories: ['performance', 'quality', 'coverage'],
+  windowSizeMs: 3600000,  // 1時間
+});
+
+// メトリクス記録
+collector.record({
+  category: 'performance',
+  name: 'build_time_ms',
+  value: 12500,
+  tags: { phase: 'implementation' },
+});
+
+// 統計取得
+const stats = collector.getStats('performance');
+// => { count: 10, min: 10000, max: 15000, avg: 12000, p95: 14500 }
+
+// レポート生成
+const report = collector.generateReport();
+```
+
+#### PatternLearningDB
+
+パターン学習と検索:
+
+```typescript
+import {
+  PatternLearningDB,
+  createPatternLearningDB,
+} from '@nahisaho/musubix-pattern-mcp';
+
+const db = createPatternLearningDB({
+  maxPatterns: 1000,
+  minConfidence: 0.7,
+});
+
+// パターン追加
+const pattern = await db.add({
+  name: 'Resource Limiter Pattern',
+  code: resourceLimiterCode,
+  source: 'fastrender-analysis',
+  confidence: 0.95,
+  tags: ['resource', 'limit', 'agent'],
+});
+
+// パターン検索
+const results = await db.query({
+  tags: ['resource'],
+  minConfidence: 0.8,
+});
+
+// 統計
+const stats = db.getStats();
+// => { total: 150, active: 145, avgConfidence: 0.88 }
+```
+
+### P4: 最低優先度
+
+#### WorkstreamManager
+
+FastRenderのワークストリーム管理を実装:
+
+```typescript
+import {
+  WorkstreamManager,
+  createWorkstreamManager,
+} from '@nahisaho/musubix-agent-orchestrator';
+
+const manager = createWorkstreamManager();
+
+// ワークストリーム作成
+const workstream = manager.createWorkstream({
+  name: 'capability_buildout',
+  description: 'CSS, layout algorithms, paint correctness',
+  owner: 'agent-001',
+  priority: 1,
+});
+
+// ステータス更新
+manager.updateWorkstream(workstream.id, {
+  status: 'active',
+  progress: 45,
+});
+
+// 一覧取得
+const activeStreams = manager.listWorkstreams({ status: 'active' });
+```
+
+#### TestPlacementValidator
+
+テスト配置ルールの検証:
+
+```typescript
+import {
+  TestPlacementValidator,
+  createTestPlacementValidator,
+} from '@nahisaho/musubix-codegraph';
+
+const validator = createTestPlacementValidator({
+  rules: [
+    { pattern: '**/*.test.ts', placement: 'colocate' },
+    { pattern: '**/integration/**', placement: 'separate' },
+    { pattern: '**/e2e/**', placement: 'dedicated' },
+  ],
+});
+
+// 検証
+const result = validator.validate({
+  sourceFile: 'src/feature.ts',
+  testFile: 'src/feature.test.ts',
+});
+// => { valid: true, rule: 'colocate-unit-tests' }
+
+// サマリー取得
+const summary = validator.getSummary();
+// => { total: 100, valid: 95, violations: 5 }
+```
+
+---
+
+## 使用例
+
+### FastRenderスタイルのワークフロー
+
+```typescript
+import {
+  createExtendedGateRunner,
+  createTriageEngine,
+  createNonNegotiablesEngine,
+  createResourceLimiter,
+} from '@nahisaho/musubix-workflow-engine';
+
+// サービス初期化
+const triageEngine = createTriageEngine();
+const nonNegotiables = createNonNegotiablesEngine();
+const resourceLimiter = createResourceLimiter(defaultLimits);
+
+// ゲートランナー設定
+const runner = createExtendedGateRunner({
+  services: {
+    triageEngine,
+    nonNegotiablesEngine: nonNegotiables,
+  },
+});
+
+// フェーズ開始時のゲート実行
+const entryResult = await runner.executePhaseGates('implementation', 'entry');
+
+if (!entryResult.passed) {
+  // P0-P1の問題が検出された
+  for (const failure of entryResult.failures) {
+    console.error(`[${failure.gate}] ${failure.message}`);
+  }
+  process.exit(1);
+}
+
+// 実装作業...
+
+// フェーズ終了時のゲート実行
+const exitResult = await runner.executePhaseGates('implementation', 'exit');
+```
+
+### トリアージフロー
+
+```typescript
+import { createTriageEngine } from '@nahisaho/musubix-workflow-engine';
+
+const triage = createTriageEngine();
+
+// 問題をトリアージ
+function handleIssue(issue: Issue) {
+  const priority = triage.triage({
+    type: issue.type,
+    severity: issue.severity,
+    urgency: issue.urgency,
+    impact: issue.impact,
+    blocksNewWork: issue.blocksNewWork,
+  });
+
+  // P0-P2は即座に対応
+  if (priority.priority <= 2) {
+    return assignToOnCall(issue, priority);
+  }
+
+  // P3-P5はバックログへ
+  return addToBacklog(issue, priority);
+}
+```
+
+---
+
+## まとめ
+
+### FastRenderから学んだこと
+
+1. **構造化されたトリアージが重要** - P0-P5の明確な優先度で作業を組織化
+2. **非交渉事項を定義する** - 品質の最低ラインを明確に
+3. **リソース制限を徹底する** - 暴走を防ぐ外部制限
+4. **ワーカーの「完了」を定義する** - 測定可能なデルタがなければ完了ではない
+5. **ワークストリームを分離する** - 責務の明確な分離
+
+### MUSUBIX v3.6.0の成果
+
+| 項目 | 値 |
+|-----|---|
+| 新規コンポーネント | 12 |
+| 新規テスト | 253 |
+| テスト合格率 | 100% |
+| 対応パッケージ | 6 |
+| 追加コード行 | +11,878 |
+
+### 今後の展望
+
+- MCPツールとしての公開
+- Claude Codeスキルとしての統合
+- より高度なトリアージアルゴリズム
+- マルチエージェント協調サポート
+
+---
+
+## 参考リンク
+
+- [Cursor Blog: 長時間稼働する自律型コーディングをスケールさせる](https://cursor.com/ja/blog/scaling-agents)
+- [FastRender GitHub](https://github.com/wilsonzlin/fastrender)
+- [MUSUBIX GitHub](https://github.com/nahisaho/MUSUBIX)
+- [MUSUBIX npm](https://www.npmjs.com/package/@nahisaho/musubix-core)
+
+---
+
+**Author**: MUSUBIX Team  
+**Version**: 3.6.0  
+**Date**: 2026-01-23