takt 0.1.4 → 0.1.6

package/resources/global/ja/agents/expert-review/frontend-reviewer.md

@@ -36,6 +36,15 @@
 
 ### 1. コンポーネント設計
 
+**原則: 1ファイルにベタ書きしない。必ずコンポーネント分割する。**
+
+**分離が必須なケース:**
+- 独自のstateを持つ → 必ず分離
+- 50行超のJSX → 分離
+- 再利用可能 → 分離
+- 責務が複数 → 分離
+- ページ内の独立したセクション → 分離
+
 **必須チェック:**
 
 | 基準 | 判定 |
@@ -60,8 +69,44 @@
 | Layout | 配置・構造 | `PageLayout`, `Grid` |
 | Utility | 共通機能 | `ErrorBoundary`, `Portal` |
 
+**ディレクトリ構成:**
+```
+features/{feature-name}/
+├── components/
+│   ├── {feature}-view.tsx      # メインビュー（子を組み合わせる）
+│   ├── {sub-component}.tsx     # サブコンポーネント
+│   └── index.ts
+├── hooks/
+├── types.ts
+└── index.ts
+```
+
 ### 2. 状態管理
 
+**原則: 子コンポーネントは自身で状態を変更しない。イベントを親にバブリングし、親が状態を操作する。**
+
+```tsx
+// ❌ 子が自分で状態を変更
+const ChildBad = ({ initialValue }: { initialValue: string }) => {
+  const [value, setValue] = useState(initialValue)
+  return <input value={value} onChange={e => setValue(e.target.value)} />
+}
+
+// ✅ 親が状態を管理、子はコールバックで通知
+const ChildGood = ({ value, onChange }: { value: string; onChange: (v: string) => void }) => {
+  return <input value={value} onChange={e => onChange(e.target.value)} />
+}
+
+const Parent = () => {
+  const [value, setValue] = useState('')
+  return <ChildGood value={value} onChange={setValue} />
+}
+```
+
+**例外（子がローカルstate持ってOK）:**
+- UI専用の一時状態（ホバー、フォーカス、アニメーション）
+- 親に伝える必要がない完全にローカルな状態
+
 **必須チェック:**
 
 | 基準 | 判定 |
@@ -81,36 +126,81 @@
 | 複数コンポーネントで共有 | Context or 状態管理ライブラリ |
 | サーバーデータのキャッシュ | TanStack Query等のデータフェッチライブラリ |
 
-### 3. パフォーマンス
+### 3. データ取得
 
-**必須チェック:**
+**原則: API呼び出しはルート（View）コンポーネントで行い、子コンポーネントにはpropsで渡す。**
 
-| 基準 | 判定 |
-|------|------|
-| 不要な再レンダリング | 最適化が必要 |
-| 大きなリストの仮想化なし | 警告 |
-| 画像の最適化なし | 警告 |
-| バンドルに未使用コード | tree-shakingを確認 |
-| メモ化の過剰使用 | 本当に必要か確認 |
+```tsx
+// ✅ CORRECT - ルートでデータ取得、子に渡す
+const OrderDetailView = () => {
+  const { data: order, isLoading, error } = useGetOrder(orderId)
+  const { data: items } = useListOrderItems(orderId)
+
+  if (isLoading) return <Skeleton />
+  if (error) return <ErrorDisplay error={error} />
+
+  return (
+    <OrderSummary
+      order={order}
+      items={items}
+      onItemSelect={handleItemSelect}
+    />
+  )
+}
 
-**最適化チェックリスト:**
-- [ ] `React.memo` / `useMemo` / `useCallback` は適切か
-- [ ] 大きなリストは仮想スクロール対応か
-- [ ] Code Splittingは適切か
-- [ ] 画像はlazy loadingされているか
+// ❌ WRONG - 子コンポーネントが自分でデータ取得
+const OrderSummary = ({ orderId }) => {
+  const { data: order } = useGetOrder(orderId)
+  // ...
+}
+```
 
-**アンチパターン:**
+**理由:**
+- データフローが明示的で追跡しやすい
+- 子コンポーネントは純粋なプレゼンテーション（テストしやすい）
+- 子コンポーネントに隠れた依存関係がなくなる
+
+**UIの状態変更でパラメータが変わる場合（週切り替え、フィルタ等）:**
+
+状態もViewレベルで管理し、コンポーネントにはコールバックを渡す。
 
 ```tsx
-// Bad: レンダリングごとに新しいオブジェクト
-<Child style={{ color: 'red' }} />
+// ✅ CORRECT - 状態もViewで管理
+const ScheduleView = () => {
+  const [currentWeek, setCurrentWeek] = useState(startOfWeek(new Date()))
+  const { data } = useListSchedules({
+    from: format(currentWeek, 'yyyy-MM-dd'),
+    to: format(endOfWeek(currentWeek), 'yyyy-MM-dd'),
+  })
+
+  return (
+    <WeeklyCalendar
+      schedules={data?.items ?? []}
+      currentWeek={currentWeek}
+      onWeekChange={setCurrentWeek}
+    />
+  )
+}
 
-// Good: 定数化 or useMemo
-const style = useMemo(() => ({ color: 'red' }), []);
-<Child style={style} />
+// ❌ WRONG - コンポーネント内で状態管理＋データ取得
+const WeeklyCalendar = ({ facilityId }) => {
+  const [currentWeek, setCurrentWeek] = useState(...)
+  const { data } = useListSchedules({ facilityId, from, to })
+  // ...
+}
 ```
 
-### 4. データフェッチ
+**例外（コンポーネント内フェッチが許容されるケース）:**
+
+| ケース | 理由 |
+|--------|------|
+| 無限スクロール | スクロール位置というUI内部状態に依存 |
+| 検索オートコンプリート | 入力値に依存したリアルタイム検索 |
+| 独立したウィジェット | 通知バッジ、天気等。親のデータと完全に無関係 |
+| リアルタイム更新 | WebSocket/Pollingでの自動更新 |
+| モーダル内の詳細取得 | 開いたときだけ追加データを取得 |
+
+**判断基準: 「親が管理する意味がない / 親に影響を与えない」ケースのみ許容。**
 
 **必須チェック:**
 
@@ -122,20 +212,195 @@ const style = useMemo(() => ({ color: 'red' }), []);
 | キャンセル処理なし | 警告 |
 | N+1クエリ的なフェッチ | REJECT |
 
-**推奨パターン:**
+### 4. 共有コンポーネントと抽象化
+
+**原則: 同じパターンのUIは共有コンポーネント化する。インラインスタイルのコピペは禁止。**
+
+```tsx
+// ❌ WRONG - インラインスタイルのコピペ
+<button className="p-2 text-[var(--text-secondary)] hover:...">
+  <X className="w-5 h-5" />
+</button>
+
+// ✅ CORRECT - 共有コンポーネント使用
+<IconButton onClick={onClose} aria-label="閉じる">
+  <X className="w-5 h-5" />
+</IconButton>
+```
+
+**共有コンポーネント化すべきパターン:**
+- アイコンボタン（閉じる、編集、削除等）
+- ローディング/エラー表示
+- ステータスバッジ
+- タブ切り替え
+- ラベル+値の表示（詳細画面）
+- 検索入力
+- カラー凡例
+
+**過度な汎用化を避ける:**
+
+```tsx
+// ❌ WRONG - IconButtonに無理やりステッパー用バリアントを追加
+export const iconButtonVariants = cva('...', {
+  variants: {
+    variant: {
+      default: '...',
+      outlined: '...',  // ← ステッパー専用、他で使わない
+    },
+    size: {
+      medium: 'p-2',
+      stepper: 'w-8 h-8',  // ← outlinedとセットでしか使わない
+    },
+  },
+})
+
+// ✅ CORRECT - 用途別に専用コンポーネント
+export function StepperButton(props) {
+  return (
+    <button className="w-8 h-8 rounded-full border ..." {...props}>
+      <Plus className="w-4 h-4" />
+    </button>
+  )
+}
+```
+
+**別コンポーネントにすべきサイン:**
+- 「このvariantはこのsizeとセット」のような暗黙の制約がある
+- 追加したvariantが元のコンポーネントの用途と明らかに違う
+- 使う側のprops指定が複雑になる
+
+### 5. 抽象化レベルの評価
+
+**条件分岐の肥大化検出:**
+
+| パターン | 判定 |
+|---------|------|
+| 同じ条件分岐が3箇所以上 | 共通コンポーネントに抽出 → **REJECT** |
+| propsによる分岐が5種類以上 | コンポーネント分割を検討 |
+| render内の三項演算子のネスト | 早期リターンまたはコンポーネント分離 → **REJECT** |
+| 型による分岐レンダリング | ポリモーフィックコンポーネントを検討 |
+
+**抽象度の不一致検出:**
+
+| パターン | 問題 | 修正案 |
+|---------|------|--------|
+| データ取得ロジックがJSXに混在 | 読みにくい | カスタムフックに抽出 |
+| ビジネスロジックがコンポーネントに混在 | 責務違反 | hooks/utilsに分離 |
+| スタイル計算ロジックが散在 | 保守困難 | ユーティリティ関数に抽出 |
+| 同じ変換処理が複数箇所に | DRY違反 | 共通関数に抽出 |
+
+**良い抽象化の例:**
+```tsx
+// ❌ 条件分岐が肥大化
+function UserBadge({ user }) {
+  if (user.role === 'admin') {
+    return <span className="bg-red-500">管理者</span>
+  } else if (user.role === 'moderator') {
+    return <span className="bg-yellow-500">モデレーター</span>
+  } else if (user.role === 'premium') {
+    return <span className="bg-purple-500">プレミアム</span>
+  } else {
+    return <span className="bg-gray-500">一般</span>
+  }
+}
+
+// ✅ Mapで抽象化
+const ROLE_CONFIG = {
+  admin: { label: '管理者', className: 'bg-red-500' },
+  moderator: { label: 'モデレーター', className: 'bg-yellow-500' },
+  premium: { label: 'プレミアム', className: 'bg-purple-500' },
+  default: { label: '一般', className: 'bg-gray-500' },
+}
+
+function UserBadge({ user }) {
+  const config = ROLE_CONFIG[user.role] ?? ROLE_CONFIG.default
+  return <span className={config.className}>{config.label}</span>
+}
+```
+
 ```tsx
-// Good: データフェッチはルートで
-function UserPage() {
-  const { data, isLoading, error } = useQuery(['user', id], fetchUser);
+// ❌ 抽象度が混在
+function OrderList() {
+  const [orders, setOrders] = useState([])
+  useEffect(() => {
+    fetch('/api/orders')
+      .then(res => res.json())
+      .then(data => setOrders(data))
+  }, [])
+
+  return orders.map(order => (
+    <div>{order.total.toLocaleString()}円</div>
+  ))
+}
 
-  if (isLoading) return <Skeleton />;
-  if (error) return <ErrorDisplay error={error} />;
+// ✅ 抽象度を揃える
+function OrderList() {
+  const { data: orders } = useOrders()  // データ取得を隠蔽
 
-  return <UserProfile user={data} />;
+  return orders.map(order => (
+    <OrderItem key={order.id} order={order} />
+  ))
 }
 ```
 
-### 5. アクセシビリティ
+### 6. データと表示形式の責務分離
+
+**原則: バックエンドは「データ」を返し、フロントエンドが「表示形式」に変換する。**
+
+```tsx
+// ✅ フロントエンド: 表示形式に変換
+export function formatPrice(amount: number): string {
+  return `¥${amount.toLocaleString()}`
+}
+
+export function formatDate(date: Date): string {
+  return format(date, 'yyyy年M月d日')
+}
+```
+
+**理由:**
+- 表示形式はUI要件であり、バックエンドの責務ではない
+- 国際化対応が容易
+- フロントエンドが柔軟に表示を変更できる
+
+**必須チェック:**
+
+| 基準 | 判定 |
+|------|------|
+| バックエンドが表示用文字列を返している | 設計見直しを提案 |
+| 同じフォーマット処理が複数箇所にコピペ | ユーティリティ関数に統一 |
+| コンポーネント内でインラインフォーマット | 関数に抽出 |
+
+### 7. パフォーマンス
+
+**必須チェック:**
+
+| 基準 | 判定 |
+|------|------|
+| 不要な再レンダリング | 最適化が必要 |
+| 大きなリストの仮想化なし | 警告 |
+| 画像の最適化なし | 警告 |
+| バンドルに未使用コード | tree-shakingを確認 |
+| メモ化の過剰使用 | 本当に必要か確認 |
+
+**最適化チェックリスト:**
+- [ ] `React.memo` / `useMemo` / `useCallback` は適切か
+- [ ] 大きなリストは仮想スクロール対応か
+- [ ] Code Splittingは適切か
+- [ ] 画像はlazy loadingされているか
+
+**アンチパターン:**
+
+```tsx
+// ❌ レンダリングごとに新しいオブジェクト
+<Child style={{ color: 'red' }} />
+
+// ✅ 定数化 or useMemo
+const style = useMemo(() => ({ color: 'red' }), []);
+<Child style={style} />
+```
+
+### 8. アクセシビリティ
 
 **必須チェック:**
 
@@ -154,7 +419,7 @@ function UserPage() {
 - [ ] スクリーンリーダーで意味が通じるか
 - [ ] カラーコントラストは十分か
 
-### 6. TypeScript/型安全性
+### 9. TypeScript/型安全性
 
 **必須チェック:**
 
@@ -165,7 +430,7 @@ function UserPage() {
 | Props型定義なし | REJECT |
 | イベントハンドラの型が不適切 | 修正が必要 |
 
-### 7. フロントエンドセキュリティ
+### 10. フロントエンドセキュリティ
 
 **必須チェック:**
 
@@ -176,7 +441,7 @@ function UserPage() {
 | 機密情報のフロントエンド保存 | REJECT |
 | CSRFトークンの未使用 | 要確認 |
 
-### 8. テスタビリティ
+### 11. テスタビリティ
 
 **必須チェック:**
 
@@ -186,7 +451,7 @@ function UserPage() {
 | テスト困難な構造 | 分離を検討 |
 | ビジネスロジックのUIへの埋め込み | REJECT |
 
-### 9. アンチパターン検出
+### 12. アンチパターン検出
 
 以下を見つけたら **REJECT**:
 
@@ -198,6 +463,8 @@ function UserPage() {
 | useEffect地獄 | 依存関係が複雑すぎる |
 | Premature Optimization | 不要なメモ化 |
 | Magic Strings | ハードコードされた文字列 |
+| Hidden Dependencies | 子コンポーネントの隠れたAPI呼び出し |
+| Over-generalization | 無理やり汎用化したコンポーネント |
 
 ## 判定基準
 
@@ -206,6 +473,7 @@ function UserPage() {
 | コンポーネント設計に問題 | REJECT |
 | 状態管理に問題 | REJECT |
 | アクセシビリティ違反 | REJECT |
+| 抽象化レベルの不一致 | REJECT |
 | パフォーマンス問題 | REJECT（重大な場合） |
 | 軽微な改善点のみ | APPROVE（改善提案は付記） |
 
@@ -223,3 +491,5 @@ function UserPage() {
 - **アクセシビリティは後付け困難**: 最初から組み込む
 - **過度な抽象化を警戒**: シンプルに保つ
 - **フレームワークの作法に従う**: 独自パターンより標準的なアプローチ
+- **データ取得はルートで**: 子コンポーネントに隠れた依存を作らない
+- **制御されたコンポーネント**: 状態の流れは単方向

package/resources/global/ja/workflows/default.yaml

@@ -1,5 +1,15 @@
 # Default TAKT Workflow
 # Plan -> Coder -> Architect Review -> AI Review -> Security Review -> Supervisor Approval
+#
+# Template Variables:
+#   {iteration}      - Workflow-wide turn count (total steps executed across all agents)
+#   {max_iterations} - Maximum iterations allowed for the workflow
+#   {step_iteration} - Per-step iteration count (how many times THIS step has been executed)
+#   {task}           - Original user request
+#   {previous_response} - Output from the previous step
+#   {git_diff}       - Current uncommitted changes (git diff)
+#   {user_inputs}    - Accumulated user inputs during workflow
+#   {report_dir}     - Report directory name (e.g., "20250126-143052-task-summary")
 
 name: default
 description: Standard development workflow with planning and specialized reviews
@@ -55,7 +65,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: plan (タスク分析)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/00-plan.md
@@ -79,7 +90,7 @@ steps:
 
       **レポート出力:** 上記の `Report File` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **レポートフォーマット:**
       ```markdown
@@ -155,7 +166,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: implement
       - Report Directory: .takt/reports/{report_dir}/
       - Report Files:
@@ -174,7 +186,7 @@ steps:
 
       **レポート出力:** 上記の `Report Files` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **Scopeレポートフォーマット（実装開始時に作成）:**
       ```markdown
@@ -279,7 +291,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: review (アーキテクチャレビュー)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/03-architect-review.md
@@ -299,7 +312,7 @@ steps:
 
       **レポート出力:** 上記の `Report File` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **レポートフォーマット:**
       ```markdown
@@ -382,7 +395,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: improve
 
       ## Architect Feedback (これが最新の指示です - 優先して対応してください)
@@ -462,7 +476,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: ai_review (AI生成コードレビュー)
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/04-ai-review.md
@@ -484,7 +499,7 @@ steps:
 
       **レポート出力:** 上記の `Report File` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **レポートフォーマット:**
       ```markdown
@@ -563,7 +578,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: ai_fix
 
       ## AI Review Feedback (これが最新の指示です - 優先して対応してください)
@@ -638,7 +654,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: security_review
       - Report Directory: .takt/reports/{report_dir}/
       - Report File: .takt/reports/{report_dir}/05-security-review.md
@@ -660,7 +677,7 @@ steps:
 
       **レポート出力:** 上記の `Report File` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **レポートフォーマット:**
       ```markdown
@@ -742,7 +759,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: security_fix
 
       ## Security Review Feedback (これが最新の指示です - 優先して対応してください)
@@ -810,7 +828,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: fix
 
       ## Architect Feedback (これが最新の指示です - 優先して対応してください)
@@ -889,7 +908,8 @@ steps:
       ```
     instruction_template: |
       ## Workflow Context
-      - Iteration: {iteration}/{max_iterations}
+      - Iteration: {iteration}/{max_iterations}（ワークフロー全体）
+      - Step Iteration: {step_iteration}（このステップの実行回数）
       - Step: supervise (final verification)
       - Report Directory: .takt/reports/{report_dir}/
       - Report Files:
@@ -917,7 +937,7 @@ steps:
 
       **レポート出力:** 上記の `Report Files` に出力してください。
       - ファイルが存在しない場合: 新規作成
-      - ファイルが存在する場合: `## Iteration {iteration}` セクションを追記
+      - ファイルが存在する場合: `## Iteration {step_iteration}` セクションを追記
 
       **Validationレポートフォーマット:**
       ```markdown