Smithery is now a part of Arcade.dev! Read more in our announcement here
タスクを単一責務原則で分解しPhase 1-13の実行可能な仕様書を生成。Phase 12は中学生レベル概念説明を含む。
Anchors: • Clean Code / 適用: SRP / 目的: タスク分解基準 • Continuous Delivery / 適用: フェーズゲート / 目的: 品質パイプライン • DDD / 適用: ユビキタス言語 / 目的:...
開発タスクを Phase 1〜13 の実行可能な仕様書へ落とし込む。SKILL.md は入口だけを持ち、詳細は references/ と LOGS.md に分離する。
| 原則 | 説明 |
|---|---|
| Script First | 決定論的処理は scripts/ で固定する |
| LLM for Judgment | 判断、設計、レビューだけを LLM が担う |
| Progressive Disclosure | 必要な reference だけを段階的に読む |
| 1 File = 1 Responsibility | 大きくなった guide は family file へ分離する |
.claude Canonical |
正本は .claude/skills/...、.agents/skills/... は mirror |
要件草案や設計草案を扱うときは、機能列挙のレビューで止めず、次の3系統を必ず通す。
特に workflow / lane / UI統合 / runtime orchestration / verify 導入を含むタスクでは、次を明示してから Phase 1 へ進む。
what / how だけでなく why now / why this way を仮説として書く。Facade / Engine / Service / Bridge / Store / UI の状態所有権を混在させない。4条件 は原則として次で評価する。
要件レビュー出力では、上の5項目を一次結論として先に示し、その後に補足として因果ループ、KJ法クラスタ、戦略仮説を足す。
| モード | 用途 | 最初に読むもの |
|---|---|---|
create |
新規 workflow を作る | references/create-workflow.md |
execute |
Phase 1〜13 を順番に実行する | references/execute-workflow.md |
update |
既存仕様書を修正する | references/phase-templates.md |
detect-unassigned |
Phase 12 の残課題を formalize する | references/phase-12-documentation-guide.md |
node scripts/detect-mode.js --request "{{USER_REQUEST}}"
タスク仕様書作成を開始する前に、以下の P50 チェックを実施する。 upstream 実装済みタスクでは「差分確認 → 回帰確認」にシフトできるため、Phase 5 の実装フェーズが軽減される。
| 確認項目 | Yes → 対応 | No → 対応 |
|---|---|---|
| current branch に実装が存在する | 差分確認・回帰テストを Phase 5 とする | 通常の実装 Phase とする |
| upstream（main等）にマージ済み | worktree に cherry-pick または再実装不要を明記 | 未マージとして扱う |
| 前提タスク（依存タスク）が完了済み | 完了済みを記録し依存チェックを省略 | Phase 1 に依存解消タスクを追加 |
標準ルール: upstream マージ済みの場合は Phase 5 冒頭に「差分確認」セクションを設け、実装の代わりに回帰確認を行う。
P50チェック結果に基づき、タスク仕様書のメタ情報に implementation_mode を明記する。
| モード | 値 | 説明 |
|---|---|---|
| 通常実装 | "new" |
RED/GREEN サイクルで新規実装を行う |
| 既実装確認 | "verify_existing" |
Phase 4 = targeted test 設計、Phase 5 = diff check に切り替える |
implementation_mode: "verify_existing" を選択した場合、Phase 4 では既実装コードのカバレッジを確認する targeted test のみを設計し、Phase 5 では git diff によるdiff確認を主要作業とする。詳細は references/phase-template-core.md の P50チェックセクションを参照。
verify_existing タスクタイプの典型的アウトカム:
verify_existing は「コードの暗黙知を明文化する」タスクタイプである。コード変更は原則ゼロまたは最小限にとどまり、以下が主な成果物となる:
| アウトカム | 例 |
|---|---|
| コメント追加 | 既存関数・型に JSDoc / インラインコメントを付与 |
| テスト追加 | 既実装コードの動作を保証する regression test を新設 |
| ドキュメント更新 | 仕様書・README・インターフェース定義の現行コードへの同期 |
コード変更なしで Phase 12 まで完了するケースが標準パターンであり、verify-all-specs が PASS しても仕様書反映が不完全な場合がある（→ references/phase-template-phase12.md §verify-all-specs が PASS しても確認すべき項目 を参照）。
agents/decompose-task.md で責務を分解する。agents/identify-scope.md で前提、制約、受入条件を固定する。
[Feedback 1 対応] Phase 1（要件定義）でタスク分類（UI task / docs-only task）を明示的に記録し、artifacts.json の artifact 命名 canonical 一覧を task root 生成時に先に確定させること。後回しにすると artifact 命名ドリフトが発生する。agents/design-phases.md と agents/generate-task-specs.md で index.md と phase-*.md を作る。agents/output-phase-files.md と agents/update-dependencies.md で artifacts.json を整える。agents/verify-specs.md、scripts/validate-phase-output.js、scripts/verify-all-specs.js で gate を通す。| Phase | 名称 | 目的 |
|---|---|---|
| 1 | 要件定義 | scope、受入条件、inventory を固定する。既存コードの命名規則（camelCase / kebab-case 等）を分析し記録する。[FB-UI-02-2] 全件 pnpm test が SIGKILL 終了するリスクがある場合は、targeted run ファイルリストを Phase 1 で事前列挙する（たとえば、メモリ制約が厳しい環境では vitest の対象ファイル指定が必須となる）。[carry-over確認] 前タスクの成果物（git log --oneline -5 で確認）を棚卸しし、今タスクの新規作業との差異を明確化すること |
| 2 | 設計 | topology、SubAgent lane、validation path を設計する。[FB-SDK-07-1] 「既存コンポーネント再利用可否」を必ず確認する。新規 UI 実装ゼロで品質・アクセシビリティ・HIG準拠を既存レベルで担保できる場合は再利用を優先する |
| 3 | 設計レビュー | Phase 4 へ進めるかを判定する |
| 4 | テスト作成 | command suite と expected result を作る。TDD Red 前に、テストパターンが Phase 1-3 で確認した命名規則と整合しているかを検証する。[Feedback P0-09-U1] private method のテストは (facade as unknown as FacadePrivate) キャストまたは public callback 経由を使う方針を Phase 4 仕様書に明記する。[FB-MSO-002] テスト実行前に依存関係整合（pnpm install + pnpm --filter @repo/shared build）を確認する。esbuild darwin バイナリ mismatch は worktree 直後に多発するため、Phase 4 開始前チェックを必須とする |
| 5 | 実装 | .claude 正本を更新し、mirror を同期する。[Feedback RT-03] 実装計画に「新規作成」「修正」ファイルパス一覧を必須記載する（見落とし防止）。[Feedback P0-09-U1] improve() フローで SDK callback が不適用な場合（llmAdapter.sendChat() 経由など）は「canUseTool 適用可能範囲と制約」を仕様書に明記する |
| 6 | テスト拡充 | fail path、回帰 guard、補助 command を追加する |
| 7 | カバレッジ確認 | concern と dependency edge の coverage を可視化する。[EMB-005-FB] NON_VISUAL + 単一クラス追加タスクでは Phase 6 に統合可能（coverage が Phase 6 テストで既に担保できる場合）。[EVALS-DOC-001] docs-only タスクでは totalTests=0 / avgCoverage=0 で EVALS.json taskMetrics を閉じ、カバレッジ確認は「対象コードなし（N/A）」として記録する |
| 8 | リファクタリング | duplicate と navigation drift を削る。[Feedback RT-03] 変更内容を 対象/Before/After/理由 テーブル形式で記録する |
| 9 | 品質保証 | line budget、link、mirror parity を一括判定する |
| 10 | 最終レビュー | acceptance criteria と blocker を判定する |
| 11 | 手動テスト | 3層評価（Semantic / Visual / AI UX）を実行し、フィードバックループで HIGH 問題を unassigned-task/ へ自動生成する。shared path alias 系は build config と test config の parity を同時確認する。[FB-MSO-003] 画面証跡取得スクリプトには try { ... } finally { browser.close(); server.close(); } パターンを標準化し、ポート解放を確実にする。[FB-LLM-MOD-05-001] screenshot ファイル名は phase spec / capture script / metadata / implementation-guide の 4 か所でセマンティック canonical 名（<component>-<state>.png）を一致させる（TC-XX 番号はメタデータ内 tc フィールドのみ）。詳細: references/phase-11-screenshot-guide.md |
| 12 | ドキュメント更新 | implementation guide、spec sync、未タスク、feedback を完了する |
| 13 | PR作成 | user の明示承認後のみ実施する |
| Task | 責務 | パターン | 入力 | 出力 |
|---|---|---|---|---|
| decompose-task | タスクを単一責務に分解 | seq | ユーザー要求 | タスク分解リスト |
| identify-scope | スコープ・前提・制約を定義 | seq | タスク分解リスト | スコープ定義 |
| design-phases | Phase構成を設計 | seq | スコープ定義 | フェーズ設計書 |
| generate-task-specs | タスク仕様書を生成 | seq | フェーズ設計書 | タスク仕様書一覧 |
| output-phase-files | 個別Markdownファイルを出力 | par | タスク仕様書一覧 | phase-*.md |
| update-dependencies | Phase間の依存関係を設定 | par | タスク仕様書一覧 | 依存関係マップ |
| verify-specs | 全13仕様書の品質検証 | seq | 検証レポート | PASS/FAIL判定 |
| update-system-specs | システム仕様書を更新 | seq | 実装サマリー | 更新完了チェック |
| generate-unassigned-task | 未完了タスク指示書を生成 | cond | レビュー課題 | unassigned-task/*.md |
凡例: seq=順次実行, par=並列実行, cond=条件分岐
| Task | 名称 | 必須 | 詳細参照 |
|---|---|---|---|
| 1 | 実装ガイド作成（2パート構成） | ✅ | 下記参照 |
| 2 | システム仕様書更新（2ステップ） | ✅ | 下記参照 |
| 3 | ドキュメント更新履歴作成 | ✅ | scripts/generate-documentation-changelog.js |
| 4 | 未タスク検出レポート作成 | ✅ | 0件でも出力必須 |
| 5 | スキルフィードバックレポート作成 | ✅ | 改善点なしでも出力必須 |
| パート | 対象読者 | 内容 |
|---|---|---|
| Part 1 | 初学者・中学生レベル | 概念説明（日常の例え話、専門用語なし） |
| Part 2 | 開発者・技術者 | 技術的詳細（スキーマ・API・コード例） |
Part 1（中学生レベル）の必須要件:
Part 2（技術者レベル）の必須要件:
implementation-guide.md へ必ず明記する## 視覚証跡 セクションに UI/UX変更なしのため Phase 11 スクリーンショット不要 と明記し、screenshots/.gitkeep を削除する。代替証跡として phase-10/final-review-result.md と phase-11/manual-test-result.md（Preload API / 型定義テスト結果を記録）を参照する| Step | 必須 | 内容 |
|---|---|---|
| Step 1-A | ✅ | タスク完了記録（「完了タスク」セクション追加 + 関連ドキュメントリンク + 変更履歴 + LOGS.md×2 + topic-map.md） |
| Step 1-B | ✅ | 実装状況テーブル更新（実装完了:「未実装」→「完了」 / 仕様書作成のみ: spec_created） |
| Step 1-C | ✅ | 関連タスクテーブル更新（仕様書内の「関連タスク」「未タスク候補」テーブルのステータス更新） |
| Step 1-D | ✅ | EVALS.json taskMetrics追記（関連スキルの qualityInsights.taskMetrics.{TASK_ID} に completedPhases / totalTests / avgCoverage / systemSpecsUpdated / unassignedTasksDetected を記録。docs-only タスクは totalTests=0 / avgCoverage=0 で固定） |
| Step 2 | 条件 | システム仕様更新（新規インターフェース追加時のみ） |
⚠️ Task 1（実装ガイド作成）との境界に注意
活動 Task 1（実装ガイド） Task 2（仕様更新） Part 1/2 実装ガイド作成 ✅ メイン責務 ❌ 対象外 aiworkflow-requirements 仕様更新 ❌ 対象外 ✅ Step 2 タスク完了記録（仕様書内） ❌ 対象外 ✅ Step 1-A 必須 LOGS.md更新（2ファイル） ❌ 対象外 ✅ Step 1-A 必須
Step 2 更新が必要な場合:
Step 2 更新が不要な場合:
spec_created UI task の Phase 12 close-out ルールspec_created ステータスの UI task でも Phase 12 実行時は Step 1-A〜1-C を N/A にせず same-wave sync で閉じる。
| Step | spec_created での扱い |
|---|---|
| Step 1-A | 完了タスク記録 + LOGS.md x2 + SKILL.md x2 + topic-map を same-wave で更新 |
| Step 1-B | 実装状況テーブルに spec_created を記録（completed ではない） |
| Step 1-C | 関連タスクテーブルのステータスを current facts へ更新 |
| Step 2 | 新規インターフェース追加がなければ N/A（ただし下記の再判定ルールを確認） |
当初 docs-only / spec_created だった task に後から code 変更が入った場合:
outputs/phase-12/*.md を同一ターンで current facts へ戻すN/A / NON_VISUAL だった Phase 11 evidence の reclassification を検討する| ソース | 確認項目 |
|---|---|
| 元タスク仕様書 | 「スコープ外」として明示された項目 |
| Phase 3/10レビュー結果 | MINOR判定の指摘事項 |
| Phase 11手動テスト | スコープ外の発見事項・改善提案 |
| コードコメント | TODO/FIXME/HACK/XXX |
describe.skip ブロック |
削除したtestid/要素名が旧参照として残存していないか（残存時はcleanupタスクをbacklogに登録） |
# 未タスク検出スクリプト
node scripts/detect-unassigned-tasks.js --scan packages/shared/src --output .tmp/unassigned-candidates.json
📖 references/phase-11-12-guide.md 📖 references/spec-update-workflow.md 📖 agents/generate-unassigned-task.md
Phase 1冒頭で仕様書に記載されたクラス名とcurrentコードベースのクラス名が一致するか確認する。 不一致の場合は命名方針をPhase 2設計より前に確定させること。
事例: LateChunkingService（仕様書記述）vs ChunkingLateChunkingAdapter（実装クラス名）のズレがPhase 1で早期検出できれば、後続フェーズの手戻りを防げた（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
Phase 11のNON_VISUALテンプレートでは証跡ファイル名を事前に宣言・固定すること。 後からファイル名が変わるとPhase 12のartifacts parity確認で矛盾が発生する。
事例: evidence-collection.md などのcanonical名を強制することで、manual-test-result.md 単独では不明瞭だった証跡範囲をdrift防止できる（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
Phase 12で「system-spec-update: 更新要」と判定した場合、 summaryファイル作成だけでなく正本仕様ファイルの実際の更新まで完了条件とする。
事例: Phase 12がsummaryファイル作成で完結せず、正本仕様の更新まで完了条件にする必要がある（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
新規クラスを設計する際は同一パッケージ内の既存クラス名と照合する。 衝突する場合はPrefix/Suffix（Adapter, Service, Handler等）で区別すること。
事例: token-levelのLateChunkingServiceと同名になりそうだったため、Phase 2でChunkingLateChunkingAdapterに改名した。早期検査が必要（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
| Version | Date | Changes |
|---|---|---|
| v10.09.61 | 2026-04-21 | TASK-RALLY-002 Phase-12 skill-feedback 反映: implementation_mode: "verify_existing" 定義に典型的アウトカム（コメント追加/テスト追加/ドキュメント更新）と false negative 注記を追記。phase-template-phase12.md に §verify-all-specs が PASS しても確認すべき項目（false negative 対策）セクションを新設（LOGS.md・lessons-learned・task-workflow・resource-map・skill-feedback の5項目）。.agents mirror を同波更新。 |
| v10.09.60 | 2026-04-21 | TASK-SC-IMPROVE-PROMPT-IMPL-001 close-out sync: NON_VISUAL + headless substitute evidence を task-local Phase 11 正本として反映し、Phase 11/12 completed 同期、artifacts.json / outputs/artifacts.json parity、unassigned follow-up 1件 formalize を同波で記録。 |
| v10.09.60 | 2026-04-22 | UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 skill-feedback 反映: Phase 12 Task 2 に Step 1-D（EVALS.json taskMetrics追記を必須ステップ化）を追加。Phase 7 実行表に [EVALS-DOC-001]（docs-only タスクの totalTests=0 / avgCoverage=0 固定ルール）を追記。LOGS.md 同波更新。 |
| v10.09.59 | 2026-04-21 | TASK-SW-TODO-001 close-out sync: verify_existing + NON_VISUAL task の Phase 11 evidence を {TASK-ID}-manual-test-report.md へ統一しつつ、manual-test-result.md に fixed phrase / 実施情報 / 仕様判断根拠 / 実行記録を集約する current pattern を close-out 実例へ反映。Phase 12 compliance-check は Task 12-1〜12-6 / Step 1-A〜1-G / Step 2 を root evidence として確認する運用を usage log に追記。 |
| v10.09.58 | 2026-04-19 | UT-IMP-WORKFLOW-CLOSEOUT-PARITY-GUARD-001 parity guard実装: validate-closeout-parity.js新規追加、complete-phase.js/verify-all-specs.js拡張。Phase 12 close-out parity 必須ゲート化。 |
| v10.09.57 | 2026-04-19 | TASK-EVALS-CONSUMER-AUDIT-001 PROPOSAL-TSC-01〜05 反映: references/phase-template-audit-task.md 新設（NON_VISUAL / 監査タスク用 Phase 再解釈マップ、185行）。phase-12-documentation-guide.md に固定フレーズ + primary evidence ルールを格上げ。phase-template-phase11.md に NON_VISUAL 分岐追加。phase-template-phase12.md に canonical N vs 必須 6 成果物分離、未タスク配置先決定フロー図、誤植修正（Task 12-1〜12-5 行削除）を反映。SKILL.md Anchors phase templates に audit-task.md 追加。LOGS.md 同波更新。 |
| v10.09.55 | 2026-04-21 | TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001 Phase12 skill-feedback 反映: Lessons Learned セクション新設（FB-01〜FB-04）。Phase 1 仕様書vsクラス名ズレ検出の必須化、Phase 11 NON_VISUAL証跡ファイル名固定、Phase 12正本仕様更新の必須ゲート化、Phase 2クラス名衝突検査を追記。.agents mirror を同波更新。 |
| v10.09.54 | 2026-04-17 | UT-9I-001 current reference sync: phase-12-documentation.md / phase-12-completion-checklist.md / phase12-checklist-definition.md / phase-12-guide.md / phase-12-tasks-guide.md を 6タスク / 6成果物 / current filename へ同期し、phase-12-docs.md 旧表記を phase-12-documentation.md へ是正。task-workflow / api-ipc / interfaces / topic-map / keywords / LOGS.md の same-wave 更新を記録。 |
| v10.09.51 | 2026-04-15 | TASK-CRON-CUSTOM-VALIDATION-001 skill-feedback 反映: 「よくある漏れ」テーブルに [VSCPKR-03]（Phase 4 でコンポーネントテスト設計時に外部 props か内部 state かを Phase 2 で確認せず TDD RED が誤前提になる）を追記。phase-template-core.md の Phase 2 セクションに「UI コンポーネントテスト設計時の Props vs internal state 確認」サブセクションを追加。LOGS.md 同波更新。 |
| v10.09.50 | 2026-04-15 | TASK-SC-IMP-CREATE-WORKFLOW-001 phase 12 close-out sync: Phase 12 の 6 成果物（implementation-guide / system-spec-update-summary / documentation-changelog / unassigned-task-detection / skill-feedback-report / phase12-task-spec-compliance-check）を同波で揃え、Part 1 / Part 2 分割、63件 Green、screenshot N/A、outputs/artifacts.json parity を current facts に反映。planned wording 直書きを排除し、runCreateWorkflow の戻り値観測を guard する方針を明文化。 |
| v10.09.50 | 2026-04-14 | UT-W3-ANALYTICS-HTTP-PROVIDER-001 phase12 current facts sync: AnalyticsHttpProvider / analytics:get-stats / sentCount / failedCount を Phase 12 current facts として追記し、implementation-guide.md / system-spec-update-summary.md / documentation-changelog.md / unassigned-task-detection.md / skill-feedback-report.md / phase12-task-spec-compliance-check.md の 6 成果物を current facts へ固定。LOGS.md 2ファイルと .agents mirror を同波更新。 / TASK-CI-OPT-001 phase 12 close-out sync: docs/30-workflows/task-ci-optimization-001/index.md の Phase 1-12 を 完了 に同期し、トップステータスを Phase 12 完了（PR未着手） に更新。artifacts.json を phase12_completed へ是正し、LOGS.md / SKILL-changelog.md / .agents mirror を same-wave で閉じる current facts を追加。 |
| v10.09.49 | 2026-04-14 | TASK-SW-FIX-STATE-DETAIL-001 skill-feedback / current facts 反映: SkillCreateWizard の stale guard、ConversationRoundStep の answers prop 再同期、generationLockRef の finally 解放、Phase 11 evidence の指し直しを current facts として追記。「Phase 12 実行時によくある漏れ」に [FB-STATE-DETAIL-001]〜[FB-STATE-DETAIL-004] を追加し、LOGS.md 同波更新。 |
| v10.09.50 | 2026-04-15 | UT-SKILL-WIZARD-NOTION-SPECIAL-CASE-ELIMINATE-001 skill-feedback / current facts 反映: SemanticLabelEntry / SemanticLabelResult / resolveLabelEntry() / resolveSemanticLabel() の current facts を raw fallback 保持へ更新し、notion 特別ケース削除を Phase 12 漏れパターンへ昇格。manual-test-result.md / implementation-guide.md / phase12-task-spec-compliance-check.md と LOGS.md 同波更新。 |
| v10.09.48 | 2026-04-13 | TASK-SW-FIX-FEEDBACK-001 skill-feedback 反映: 「よくある漏れ」テーブルに [FB-FEEDBACK-001]（LLM モード成功後に fetchSkills() 明示呼び出しを省略するとスキル一覧が未更新になる / template モードは createSkill 内部で自動呼び出し済みのためモード差異に注意）を追記。LOGS.md 2ファイル同波更新。 |
| v10.09.47 | 2026-04-13 | UT-SKILL-WIZARD-FB-05-TEST-EVIDENCE-CONSOLIDATION-001 skill-feedback 反映: Phase 11 テスト証跡テンプレートに EC-NNN / SD-NNN 採番ルール・edge case 一覧表・仕様判断根拠テーブルを導入。テスト件数サマリーを PASS/FAIL/SKIP 5列構成に改訂。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| v10.09.47 | 2026-04-13 | UT-W3-ANALYTICS-STORE-INTEGRATION-001 close-out sync: analyticsSlice.ts を helper 化し、agentSlice.ts に lifecycle wiring を追加。packages/shared/src/types/index.ts / packages/shared/index.ts で SkillAnalyticsEventType / SkillAnalyticsEvent を再公開し、task-workflow-completed・LOGS・Phase 12 outputs を current facts に同期。 |
| v10.09.46 | 2026-04-13 | TASK-UI-SCHEDULE-CRON-MONTHLY-GUARD-001 current facts sync: 「よくある漏れ」テーブルに [Feedback 5]（Phase 12 close-out で index.md / artifacts.json / outputs/artifacts.json を別 wave で更新し、phase table と台帳が一時的に不一致になる）を追記。outputs/phase-12/ current facts を monthly 逆変換の custom fallback と NON_VISUAL manual-test evidence まで反映し、LOGS.md 2ファイル同波更新。 / TASK-SW-FIX-DATAFLOW-001 current facts 反映: SkillCreationContext 導入後の dataflow（buildSkillContext / buildSkillGenerationPrompt / skill.create(..., context)）を Phase 12 close-out 観点で知見化。Phase 12 実行時によくある漏れ テーブルへ context bridge 同期漏れ（shared型・renderer store・preload/main IPC 契約の同一wave更新漏れ）を追記し、仕様と実装の乖離を防止。 |
| v10.09.45 | 2026-04-13 | TASK-UI-SCHEDULE-CRON-SEMANTIC-001 skill-feedback 反映: 「よくある漏れ」テーブルに [FB-CRONVL-001]（Phase 2 ライブラリ採用時の複合フィールド AND/OR semantics 実測確認漏れ）・[FB-CRONVL-002]（NON_VISUAL renderer utility の opt-in フラグ追加時に UI 統合経路を別タスク化することを Phase 1 で明示する）を追記。aiworkflow-requirements/SKILL.md Trigger キーワードに ValidateCronOptions / cron-parser / semantic（cronバリデーション） 等を追加。LOGS.md 2ファイル同波更新。 |
| v10.09.44 | 2026-04-12 | UT-W3-ANALYTICS-ADAPTER-001 skill-feedback 反映: 「よくある漏れ」テーブルに [UT-W3] 3件（implementation-guide.md の current contract 旧方針記述 / artifacts.json parity 未確認 / generate-index.js 省略によるインデックス stale）を追記。 |
| v10.09.44 | 2026-04-12 | TASK-CRON-SEMANTIC-VALIDATION-001 Phase 12完了・non-visual task判定基準追加: 「必須タスク」テーブルを5タスク→6タスクに修正（Task 12-6コンプライアンスチェック追加）。non-visual task判定基準テーブル（Phase 11スクリーンショットN/A・Phase 12-2 Step 2 N/A条件）を追加。未タスク0件判定ソース一覧テーブルを追加。LOGS.md 2ファイル同波更新。 |
| v10.09.43 | 2026-04-12 | UT-W3-ANALYTICS-ADAPTER-001 Phase 12 close-out sync: outputs/phase-12/ canonical 6成果物の欠落を解消し、implementation-guide.md を Part 1/Part 2 構成で current facts に再構成。artifacts.json と outputs/artifacts.json を phase12_completed + phase13 blocked で同期し、index.md phase status との同値性を回復。aiworkflow-requirements 側の analytics / trackEvent / IPC 契約 / task-workflow completed 記録を同 wave で更新し、Phase 12 root evidence を phase12-task-spec-compliance-check.md に集約。 |
| v10.09.43 | 2026-04-11 | UT-SKILL-WIZARD-W1-DESCRIBE-SKIP-CLEANUP-001 skill-feedback 反映: 「よくある漏れ」テーブルに [FB-TASK-01/02]（testid 削除後の describe.skip 内残存参照 CI 非検出問題）を追記。patterns-lessons-and-pitfalls.md に describe.skip 内 testid 残存 pitfall を追加。aiworkflow-requirements/references/lessons-learned-skill-wizard-redesign.md に L-SKIP-001/002 を追加。LOGS.md 2ファイル同波更新。 |
| v10.09.42 | 2026-04-11 | UT-SKILL-WIZARD-W0-CATEGORY-LABEL-MAPPING-001 skill-feedback 反映: Phase 12 と Phase 13 の境界テーブルに Task 12-6（phase12-task-spec-compliance-check.md を root evidence として残す）を追加し Task 12-5 の責務を分離。SKILL_CATEGORY_LABELS satisfies Record<SkillCategory, string> パターンによるコンパイル時ラベルドリフト防止を lessons-learned に記録。台帳3点同期（workflow spec / artifacts.json / outputs/artifacts.json）を Phase 12 標準チェックリストに追加。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| v10.09.41 | 2026-04-11 | UT-SKILL-WIZARD-FB-04-WORKFLOW-LEDGER-SYNC skill-feedback 反映: 「よくある漏れ」テーブルに [FB-04]（Phase 12 close-out 時の ledger / lane index / artifacts 三者同期漏れ）を追記し、Step 1-A での5ファイル同一wave同期チェックを明文化。mirror (.agents) 側にも同差分を反映。 |
| v10.09.41 | 2026-04-11 | UT-SKILL-WIZARD-W0-CATEGORY-LABEL-MAPPING-001 skill-feedback 反映: Phase 12 と Phase 13 の境界テーブルに Task 12-6（phase12-task-spec-compliance-check.md を root evidence として残す）を追加し Task 12-5 の責務を分離。SKILL_CATEGORY_LABELS satisfies Record<SkillCategory, string> パターンによるコンパイル時ラベルドリフト防止を lessons-learned に記録。台帳3点同期（workflow spec / artifacts.json / outputs/artifacts.json）を Phase 12 標準チェックリストに追加。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| v10.09.40 | 2026-04-08 | TASK-SC-13-VERIFY-CHANNEL-IMPLEMENTATION skill-feedback 反映: 「よくある漏れ」テーブルに Feedback SC-13-1（ALLOWED_INVOKE_CHANNELS 追記漏れ対策）・SC-13-2（公開 surface と内部エンジン名衝突時の DTO 変換表必須化）を追記。api-ipc-system-skill-creator-part2.md に skill-creator:verify チャンネル仕様・DTO 型定義・設計注意点を追加。lessons-learned-ipc-preload-runtime-2026-04.md に L-SC13-IPC-001/002 を追加。LOGS.md 同波更新。 |
| v10.09.39 | 2026-04-08 | UT-SKILL-WIZARD-W0-RUNTIME-VALIDATION-001 skill-feedback 反映: 「よくある漏れ」テーブルに Feedback W0-RV-001（境界値テスト文字列の実文字数確認）を追記。aiworkflow-requirements/references/lessons-learned-current-2026-04.md に L-RV-001・L-RV-002 を追加。LOGS.md 2ファイル + SKILL.md 同波更新。 |
| v10.09.38 | 2026-04-08 | UT-SKILL-WIZARD-W1-par-02b skill-feedback 反映: patterns-lessons-and-pitfalls.md に renderer node-only import pitfall を追加。phase-template-phase11.md に UI task VISUAL デフォルトガイドを追加。phase-12-documentation-guide.md Task 12-6 に identifier consistency check を追加。「よくある漏れ」テーブルに Feedback W1-02b-1〜4 を追記。LOGS.md 2ファイル + SKILL.md 2ファイル同波更新。 |
| v6.18.12〜v6.18.27 | 2026-03-26〜2026-04-07 | 詳細履歴はアーカイブへ移管済み。内容は LOGS.md / references/logs-archive-2026-march.md を参照 |
| 観点 | 記録内容 |
|---|---|
| テンプレート改善 | Phaseテンプレートの漏れや曖昧さ |
| ワークフロー改善 | 機械検証や手順分岐の改善余地 |
| ドキュメント改善 | 再利用しやすい横断ガイドライン化の候補 |
出力:
outputs/phase-12/skill-feedback-report.mdSkillCreateWizard の template error は stale guard を入れないと、キャンセル後の遅延 reject で古いエラーが再表示される。ConversationRoundStep は answers prop 変更時に内部 state を再同期しないと、前回回答が残ったまま次のラウンドに混入する。generationLockRef は finally で必ず解放しないと、次回生成がロックされたままになる。outputs/phase-11/ の実物と current facts を一致させ、スクリーンショット参照先の指し直しを同波で更新する。| 漏れパターン | 防止方法 |
|---|---|
[FB-NOTION-001] raw 値を toLowerCase() したまま fallback すると Jira / Markdown / JSON の原表記が壊れる |
lookup は正規化しても、fallback は原入力の表記を保持する。resolveLabelEntry() では map lookup と fallback を分け、未登録値は元文字列をそのまま返す |
| [FB-STATE-DETAIL-001] template error のキャンセル後に stale guard がなく、遅延 reject が古いエラーを再表示する | template error 系の catch/finally では cancelled / active 系の stale guard を必ず確認し、キャンセル後の state 更新を遮断する。最初からやり直す ボタンを出す場合も、非アクティブ化後の再表示防止を先に実装する |
[FB-STATE-DETAIL-002] ConversationRoundStep の answers prop が変わっても internal state が再初期化されず、前回の回答が次ラウンドへ残留する |
answers を props で受けるコンポーネントは、prop 変更を起点に internal state を再同期する effect を持たせる。初期化ロジックと手動編集ロジックを分け、useState 初期値だけに依存しない |
[FB-STATE-DETAIL-003] generationLockRef の解放漏れで、template / LLM いずれの生成フローも次回実行できなくなる |
生成フローでは try/catch よりも finally を解放責務の唯一の出口として扱う。成功・失敗・キャンセルの全経路で generationLockRef.current = false を実行することを Phase 5/11/12 の共通パターンとして固定する |
| [FB-STATE-DETAIL-004] Phase 11 の evidence が画面と current facts で食い違い、スクリーンショット参照先の指し直しが漏れる | Phase 11 の証跡更新では、画像ファイル・screenshot-plan.json・phase11-capture-metadata.json・Phase 12 implementation-guide.md の参照先を同一 wave で更新する。証跡の実体とドキュメントのリンク先を別 wave で動かさない |
| [FB-VISUAL-CAP-001] Phase 11 の screenshot ファイル名が旧 TC 命名のまま残り、metadata / manual-test / implementation-guide / completed ledger の canonical 名が分断される | VISUAL タスクの close-out では screenshot 名を task root で先に canonical 化し、phase11-capture-metadata.json / manual-test-result.md / implementation-guide.md / completed ledger を同一 wave で更新する。画像ファイル名は 1 つの正本に揃え、旧名は evidence 目的以外で残さない |
[UT-W3] implementation-guide.md が current contract（trackEvent → analyticsAdapter → analytics:send）ではなく旧方針（renderer-local no-op）のまま記述される |
Phase 12 Task 12-1 で implementation-guide.md を作成する前に trackEvent.ts の prod sink 分岐と analyticsAdapter.ts の存在を確認し、current contract を先に記録してから説明文を書く |
[UT-W3] artifacts.json / outputs/artifacts.json parity 未確認のまま Phase 12 を閉じる |
Phase 12 完了前に artifacts.json と outputs/artifacts.json の両ファイルを diff し、phase12_completed + phase13_blocked が同値であることを確認する |
[UT-W3] Phase 12 Task 12-2/12-3/12-6 で generate-index.js 実行を省略してインデックスが stale になる |
Task 12-2（システム仕様書更新）・Task 12-3（changelog 更新）・Task 12-6（compliance check）の完了後は node .claude/skills/aiworkflow-requirements/scripts/generate-index.js を必ず実行し、インデックス stale を防ぐ |
[UT-W3] analytics:get-stats / sentCount / failedCount を documentation-changelog / system-spec-update-summary へ書き忘れ、送信契約のみで完了扱いにする |
Phase 12 Task 12-2/12-5 では analytics:send に加えて stats API と counters を current facts へ同時記録し、analyticsHandler.ts の skipped 返却も確認する |
| Step 1-C（関連タスクテーブル）を未実行 | spec-update-workflow.md の「確認すべきファイル」表を実行前に必ず読む |
| topic-map.md 未更新 | 仕様書に新規セクション追加時は必ず topic-map.md のエントリも追加 |
| documentation-changelog.md が不完全 | 全Step（1-A/1-B/1-C/Step 2）の結果を個別に明記する（「該当なし」も記録） |
system-spec-update-summary.md を未作成で完了扱い |
Phase 12成果物一覧と outputs/phase-12/ 実体を1対1で突合し、不足ファイルは完了前に作成する |
| LOGS.md が1ファイルのみ更新 | 必ず aiworkflow-requirements/LOGS.md と task-specification-creator/LOGS.md の両方 |
| 完了タスクセクションが簡略形式 | spec-update-workflow.md のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
artifacts.json と outputs/artifacts.json が不一致 |
Phase 12完了前に2ファイルを同期し、completed成果物の参照切れを0件にする |
[Feedback 5] Phase 12 close-out で index.md / artifacts.json / outputs/artifacts.json を別 wave で更新して phase table と台帳が一時的に不一致になる |
Phase 12 完了前に index.md の Phase 表、task root artifacts.json、outputs/artifacts.json を同一ターンで更新し、phase status の二重化を防ぐ |
| [FB-04] Phase 12 close-out で backlog ledger / completed ledger / lane index / workflow artifacts / skill artifacts の5点を同一waveで同期せず、タスク状態が二重化する | Step 1-A の開始時に三者同期チェックリストで5ファイルを1件ずつ突合し、同一ターンで一括更新する。更新後は validate-phase-output.js --phase 12 と diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator で整合を確認する |
設計タスクの workflow root を completed にしてしまう |
workflow root は implementation_ready、completed ledger は spec_created に分離する |
| Phase 10 MINOR指摘を未タスク化せず進行 | Phase 10レビュー前に unassigned-task-guidelines.md を読み、MINOR判定→未タスク化ルールを確認 |
| 未タスク検出レポートで0件判定のまま未修正 | Phase 10 MINOR指摘は必ず未タスク化の対象。「機能に影響なし」は不要判定の理由にならない |
task-workflow.md の未タスクリンクが参照切れ |
Step 1-E後に verify-unassigned-links.js を実行して ALL_LINKS_EXIST を確認する |
[Feedback 2] Phase 12 着手時に outputs/artifacts.json と phase spec の artifact 名が照合されない |
Phase 12 の 最初の作業として outputs/artifacts.json と各 phase-*.md に記載されたartifact名を1対1で突合し、不一致があれば着手前に修正する |
| [Feedback 3] Phase 11 の UI task / docs-only task 判定がずれる | Phase 1 で記録したタスク分類（UI task / docs-only task）を Phase 11 着手時に必ず参照する。分類が変わっていた場合は再判定を明示する |
[Feedback W0-01] shared 型追加で root @repo/shared に再エクスポートすると SkillCategory が衝突する |
新しい共有型は subpath export（例: @repo/shared/types/skillCreator）に閉じ、既存 root barrel は触らない。phase-12-documentation.md と system spec の両方で公開経路を明記する |
| [Feedback P0-09-U1-1] Phase 4 仕様書に private method テスト方針が未記載 | (facade as unknown as FacadePrivate) キャストと public callback 経由テストの2択を Phase 4 仕様書に必ず明記する |
[Feedback P0-09-U1-2] improve() フローの canUseTool 配線先（SDK callback vs applyImprovement()）が仕様書から読み取れない |
Phase 5 仕様書のタスク2に「canUseTool 適用可能範囲と制約」セクションを設け、llmAdapter.sendChat() 経由時は SDK callback 非適用と明記する |
| [Feedback BEFORE-QUIT-001] Phase 11 が非 visual task なのに実地操作を要求してしまう | Phase 11 では「実地操作不可」を明記し、自動テスト結果 + 既知制限リストを代替記録として残す |
| [Feedback BEFORE-QUIT-002] Phase 7 coverage が全ファイル一律指定だと局所検証の意図がぼやける | Phase 7 では coverage の対象範囲を明示し、変更したファイル/ブロック以外を対象外として書く |
| [Feedback BEFORE-QUIT-003] Phase 12 の system-spec update で workflow-local と global sync が混在する | documentation-changelog.md で workflow-local 同期と global skill sync を別ブロックで記録する |
| [Feedback 4] Phase 11 NON_VISUAL のとき manual-test-result.md の証跡メタが薄い | Phase 11 が NON_VISUAL の場合、manual-test-result.md のメタ情報に「証跡の主ソース（自動テスト名/件数）」と「スクリーンショットを作らない理由」を明記する。空メタでは reviewer が意図を読み取れない |
| [Feedback 5] Phase 7 の coverage 目標が広域指定のとき変更行の保護確認が曖昧になる | Phase 7 のカバレッジ目標が「全体 X%」など広域指定のとき、変更した関数/ブロックの line カバレッジと branch カバレッジの実測値を証跡に残す（例: applyWorkflowSnapshot 付近の line 100% / branch 100%） |
| [Feedback 6] ViewType を追加した際に navigation 契約・store 型・既存テストの3点更新が漏れる | store/types.ts（ViewType union）/ skillLifecycleJourney.ts（正規化関数・定数）/ renderView テスト を same-wave で更新し、ui-ux-navigation.md の ViewType テーブルも同時同期する。Phase 1 設計メモに「追加 ViewType: XYZ」を明示しておくと漏れが防げる |
| [FB-UI-02-1] Phase 9 QA で「ファイル削除」を PASS 基準にすると stub 化タスクが FAIL 扱いになる | Phase 9 の削除確認は「git delete されている OR export {} stub 化かつ live import ゼロのいずれか」を PASS とする。たとえば、廃止ファイルを stub 化した場合は grep -rn "import.*廃止ファイル名" src/ でゼロ件を証跡に残す |
[Feedback TASK-UI-04] 実装完了後に artifacts.json status が spec_created / in_progress のまま放置される |
実装 Phase（Phase 5 or 最終実装 Phase）完了時に complete-phase.js を必ず実行し、status を completed に更新する。実装完了と仕様書ステータス更新は同一 wave で行う（後回しは乖離蓄積の主因）。有効値: spec_created / in_progress / completed / phase12_completed |
[FB-DATAFLOW-001] SkillCreationContext 追加時に shared 型・renderer store・preload/main IPC の context bridge 同期が同一waveで更新されず、implementation-guide.md と実コードの dataflow が乖離する |
Phase 12 Task 12-1/12-2 の開始前に buildSkillContext / buildSkillGenerationPrompt / skill.create(..., context) の3点を契約チェックとして固定し、packages/shared・apps/desktop/src/renderer・apps/desktop/src/main を同一 wave で突合する。ズレがあれば close-out 前に仕様と成果物（phase spec / artifacts）を同時修正する |
| [FB-SDK-07-2] Phase 1 で新規 IPC surface を定義する際に Preload API 経由が明記されない | Phase 1（要件定義）では新規 IPC surface を定義する場合、「Preload API 経由必須」を明記する。直接 ipcRenderer.on は禁止パターンとして記録する |
| [FB-SDK-07-4] Phase 1 で既存 API の命名パターンを確認せずに新規 API を命名し、Phase 3 で MINOR 指摘を受ける | Phase 1（要件定義）では既存の safeOn / safeInvoke 等の命名パターンを確認し、新規 API の命名規則一貫性を担保する。命名ドリフトは Phase 3 レビューゲートの MINOR 指摘の主要因となる |
[Feedback W1-02b-1] UI task の screenshot-plan.json が mode: "NON_VISUAL" のまま Phase 11 を迎えやすい |
UI コンポーネント変更タスクでは screenshot-plan.json 生成時に mode: "VISUAL" をデフォルトにする。phase11-capture-metadata.json の taskId が現行タスク ID と一致するか Phase 11 着手前に確認する（jq '.taskId' outputs/phase-11/phase11-capture-metadata.json） |
| [Feedback W1-02b-2] multi-step wizard 設計で「ステップ間の state ownership と引き渡し項目」が Phase 2 設計書に未記載 | Phase 2（設計）でウィザード / マルチステップ UI を設計する場合、「ステップ間 state 引き渡しテーブル」を必須セクションとして設ける。smartDefaults など推論値の反映タイミング（初回のみ / 都度上書き / ユーザー優先）は decision 欄で固定する |
[Feedback W1-02b-3] implementation-guide.md の callback 名・props 名が実装と一致していない（identifier drift） |
Phase 12 Task 12-6 で implementation-guide.md 内の識別子を現行コードで grep 確認する。スニペットは型定義・props interface から引用し、手書き snippets を避ける |
| [Feedback W1-02b-4] renderer UI コンポーネントで node-only パッケージを直接 import し、Vite browser bundle が runtime error になる | renderer コンポーネントでは node-only パッケージ（node-cron 等）を直接 import しない。cron/schedule 検証は browser-safe ユーティリティに切り出す。Phase 11 capture 前に「ブラウザで実際に route を開く smoke test」を必須にする |
[Feedback W0-RV-001] minLength / maxLength のテストケースで境界値文字列の実文字数を確認せずに誤った長さで書く（例: "十文字以上の目的" = 実際は 7 文字） |
テスト文字列を書く前に "...".length で実文字数を確認する。日本語の漢数字表記の意味と .length は別物。境界値テストは // length: N コメントを付けてから書く |
[Feedback SC-13-1] IPC surface 追加時に apps/desktop/src/preload/channels.ts の ALLOWED_INVOKE_CHANNELS への追記が漏れる |
IPC surface 追加タスクでは Phase 2 成果物のチェックリストに「ALLOWED_INVOKE_CHANNELS への追記」を必須項目として記載する。shared/ipc/channels.ts への定数追加だけでは Renderer から呼び出せない |
[Feedback SC-13-2] 公開 IPC メソッド名（verify(skillName, ...)）と内部エンジンメソッド名（verifySkill(skillDir)）が酷似し Phase 2 設計時に責務が不明確になる |
公開 surface と内部エンジンで名前が近い場合、Phase 2 成果物に「内部型 → 公開 DTO 変換表」と「解決レイヤ名称（例: resolveVerifySkillDir）」を必須セクションとして設ける |
[Feedback VSCPKR-01] JSDoc コメント内に */ を含む説明（例: ステップ値 */n）があると esbuild がコメント終端と誤認識しパースエラーになる |
cron 式や数式を JSDoc コメント内で説明する場合は */ を避け、* /n のようにスペースを挿入するか、コードブロック（```）形式で書く。@example タグ内の inline cron 式も同様 |
[Feedback VSCPKR-02] happy-dom 環境で vi.stubGlobal("window", ...) でウィンドウ全体を置き換えると React 内部の instanceof HTMLElement が常に false になり、コンポーネントテストが壊れる |
window.api などの Electron Preload API をモックする場合は Object.defineProperty(window, "api", { value: mockApi, writable: true }) を使う。vi.stubGlobal("window", ...) は使用禁止 |
| [VSCPKR-03] Phase 4 でコンポーネントテストを設計する際に、テストで操作する入力が外部 props か内部 state かを Phase 2 で確認しておらず、TDD RED フェーズで「テストが通らない」問題が props/state の混同に起因することに気づかない | Phase 2（設計）で UI コンポーネントのモード管理方法を明記する（例: "isAdvancedMode は内部 state"）。Phase 4 仕様書に「テスト操作対象は internal state か external prop か」を明記し、TDD RED を書く前にコンポーネントの props interface と内部 useState を区別する |
| [FB-CRONVL-001] Phase 2 でサードパーティライブラリを採用する際に、複合フィールド（day-of-month × day-of-week）の組み合わせ動作（AND/OR semantics）を実測確認しないと、Phase 5 で設計変更が必要になり TDD の期待値を修正し直す手戻りが発生する | Phase 2 設計書の「ライブラリ選定」セクションに「複合フィールドの semantics 実測確認」を必須チェック項目として記載する。例: CronExpressionParser.parse("0 0 31 2 1") の next-execution 計算結果で AND/OR 判定を確認する。期待 semantics と一致しない場合は safe-side 判定（到達不能を常にエラー）への方針変更を Phase 2 で決定する |
[FB-CRONVL-002] renderer utility に opt-in フラグ（例: semantic?: boolean）を追加する場合、Phase 1 スコープで「UI 呼び出し経路は別タスク化する」を明示しないと、UI 統合の担当タスクが曖昧なまま積み残される |
Phase 1（要件定義）で opt-in フラグを設計する際は、「このフラグを UI から有効化するタイミングと担当タスク ID は別タスクで明示する」を scope out として明記する。NON_VISUAL タスクでは特に「将来の UI 統合経路 = 未タスク化候補」を Phase 1 成果物に書き残す |
[FB-TASK-01/02] testid 削除・改名後に describe.skip ブロック内の旧参照が残存し CI に検出されない（スキップ済みテストは実行されないため型エラーも発生しない） |
testid 削除タスクでは Phase 5 完了チェックとして grep -rn "<削除testid>" apps/ を実行し、describe.skip 内を含む全残存参照をゼロにする。同一 wave で削除しないと cleanup タスクが積み残される |
| [WEEKGRD-01] NON_VISUALタスクのPhase 11では、source-level PASSと環境ブロッカーを混在させて記録してしまい、後からブロッカーの性質が判断できなくなる | source-level PASSと環境ブロッカー（esbuild mismatch等）を別カテゴリで記録する。製品コードの問題と環境起因の問題は分離しないと、次回タスクで同じ混乱が起きる |
| [WEEKGRD-02] 純粋関数ガードの実装方針として「例外スロー」を選択してしまい、呼び出し元への影響が広がる | 純粋関数ガードのデフォルト戦略は「例外なし・無効値返却（空文字等）」とする。入力バリデーションは呼び出し元（UIレイヤ等）に委ね、関数自体は防御的な値返却に徹する |
[WEEKGRD-03] NON_VISUALタスクの ui-sanity-visual-review.md に非該当理由が明記されず、reviewerがNON_VISUAL判断の根拠を読み取れない |
NON_VISUALタスクでは ui-sanity-visual-review.md の冒頭に「NON_VISUAL宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |
| 漏れパターン | 防止方法 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
[UT-W3] implementation-guide.md が current contract（trackEvent → analyticsAdapter → analytics:send）ではなく旧方針（renderer-local no-op）のまま記述される |
Phase 12 Task 12-1 で implementation-guide.md を作成する前に trackEvent.ts の prod sink 分岐と analyticsAdapter.ts の存在を確認し、current contract を先に記録してから説明文を書く |
[UT-W3] artifacts.json / outputs/artifacts.json parity 未確認のまま Phase 12 を閉じる |
Phase 12 完了前に artifacts.json と outputs/artifacts.json の両ファイルを diff し、phase12_completed + phase13_blocked が同値であることを確認する |
[UT-W3] Phase 12 Task 12-2/12-3/12-6 で generate-index.js 実行を省略してインデックスが stale になる |
Task 12-2（システム仕様書更新）・Task 12-3（changelog 更新）・Task 12-6（compliance check）の完了後は node .claude/skills/aiworkflow-requirements/scripts/generate-index.js を必ず実行し、インデックス stale を防ぐ |
[UT-W3] shared 型を追加したのに types/index.ts / package index / consumer wiring のどれかが残り、Phase 12 が false complete になる |
|
| Step 1-C（関連タスクテーブル）を未実行 | spec-update-workflow.md の「確認すべきファイル」表を実行前に必ず読む |
| topic-map.md 未更新 | 仕様書に新規セクション追加時は必ず topic-map.md のエントリも追加 |
| documentation-changelog.md が不完全 | 全Step（1-A/1-B/1-C/Step 2）の結果を個別に明記する（「該当なし」も記録） |
system-spec-update-summary.md を未作成で完了扱い |
Phase 12成果物一覧と outputs/phase-12/ 実体を1対1で突合し、不足ファイルは完了前に作成する |
| LOGS.md が1ファイルのみ更新 | 必ず aiworkflow-requirements/LOGS.md と task-specification-creator/LOGS.md の両方 |
| 完了タスクセクションが簡略形式 | spec-update-workflow.md のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
artifacts.json と outputs/artifacts.json が不一致 |
Phase 12完了前に2ファイルを同期し、completed成果物の参照切れを0件にする |
| [FB-04] Phase 12 close-out で backlog ledger / completed ledger / lane index / workflow artifacts / skill artifacts の5点を同一waveで同期せず、タスク状態が二重化する | Step 1-A の開始時に三者同期チェックリストで5ファイルを1件ずつ突合し、同一ターンで一括更新する。更新後は validate-phase-output.js --phase 12 と diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator で整合を確認する |
設計タスクの workflow root を completed にしてしまう |
workflow root は implementation_ready、completed ledger は spec_created に分離する |
| Phase 10 MINOR指摘を未タスク化せず進行 | Phase 10レビュー前に unassigned-task-guidelines.md を読み、MINOR判定→未タスク化ルールを確認 |
| 未タスク検出レポートで0件判定のまま未修正 | Phase 10 MINOR指摘は必ず未タスク化の対象。「機能に影響なし」は不要判定の理由にならない |
task-workflow.md の未タスクリンクが参照切れ |
Step 1-E後に verify-unassigned-links.js を実行して ALL_LINKS_EXIST を確認する |
[Feedback 2] Phase 12 着手時に outputs/artifacts.json と phase spec の artifact 名が照合されない |
Phase 12 の 最初の作業として outputs/artifacts.json と各 phase-*.md に記載されたartifact名を1対1で突合し、不一致があれば着手前に修正する |
| [Feedback 3] Phase 11 の UI task / docs-only task 判定がずれる | Phase 1 で記録したタスク分類（UI task / docs-only task）を Phase 11 着手時に必ず参照する。分類が変わっていた場合は再判定を明示する |
[Feedback W0-01] shared 型追加で root @repo/shared に再エクスポートすると SkillCategory が衝突する |
新しい共有型は subpath export（例: @repo/shared/types/skillCreator）に閉じ、既存 root barrel は触らない。phase-12-documentation.md と system spec の両方で公開経路を明記する |
| [Feedback P0-09-U1-1] Phase 4 仕様書に private method テスト方針が未記載 | (facade as unknown as FacadePrivate) キャストと public callback 経由テストの2択を Phase 4 仕様書に必ず明記する |
[Feedback P0-09-U1-2] improve() フローの canUseTool 配線先（SDK callback vs applyImprovement()）が仕様書から読み取れない |
Phase 5 仕様書のタスク2に「canUseTool 適用可能範囲と制約」セクションを設け、llmAdapter.sendChat() 経由時は SDK callback 非適用と明記する |
| [Feedback BEFORE-QUIT-001] Phase 11 が非 visual task なのに実地操作を要求してしまう | Phase 11 では「実地操作不可」を明記し、自動テスト結果 + 既知制限リストを代替記録として残す |
| [Feedback BEFORE-QUIT-002] Phase 7 coverage が全ファイル一律指定だと局所検証の意図がぼやける | Phase 7 では coverage の対象範囲を明示し、変更したファイル/ブロック以外を対象外として書く |
| [Feedback BEFORE-QUIT-003] Phase 12 の system-spec update で workflow-local と global sync が混在する | documentation-changelog.md で workflow-local 同期と global skill sync を別ブロックで記録する |
| [Feedback 4] Phase 11 NON_VISUAL のとき manual-test-result.md の証跡メタが薄い | Phase 11 が NON_VISUAL の場合、manual-test-result.md のメタ情報に「証跡の主ソース（自動テスト名/件数）」と「スクリーンショットを作らない理由」を明記する。空メタでは reviewer が意図を読み取れない |
| [Feedback 5] Phase 7 の coverage 目標が広域指定のとき変更行の保護確認が曖昧になる | Phase 7 のカバレッジ目標が「全体 X%」など広域指定のとき、変更した関数/ブロックの line カバレッジと branch カバレッジの実測値を証跡に残す（例: applyWorkflowSnapshot 付近の line 100% / branch 100%） |
| [Feedback 6] ViewType を追加した際に navigation 契約・store 型・既存テストの3点更新が漏れる | store/types.ts（ViewType union）/ skillLifecycleJourney.ts（正規化関数・定数）/ renderView テスト を same-wave で更新し、ui-ux-navigation.md の ViewType テーブルも同時同期する。Phase 1 設計メモに「追加 ViewType: XYZ」を明示しておくと漏れが防げる |
| [FB-UI-02-1] Phase 9 QA で「ファイル削除」を PASS 基準にすると stub 化タスクが FAIL 扱いになる | Phase 9 の削除確認は「git delete されている OR export {} stub 化かつ live import ゼロのいずれか」を PASS とする。たとえば、廃止ファイルを stub 化した場合は grep -rn "import.*廃止ファイル名" src/ でゼロ件を証跡に残す |
[Feedback TASK-UI-04] 実装完了後に artifacts.json status が spec_created / in_progress のまま放置される |
実装 Phase（Phase 5 or 最終実装 Phase）完了時に complete-phase.js を必ず実行し、status を completed に更新する。実装完了と仕様書ステータス更新は同一 wave で行う（後回しは乖離蓄積の主因）。有効値: spec_created / in_progress / completed / phase12_completed |
[FB-DATAFLOW-001] SkillCreationContext 追加時に shared 型・renderer store・preload/main IPC の context bridge 同期が同一waveで更新されず、implementation-guide.md と実コードの dataflow が乖離する |
Phase 12 Task 12-1/12-2 の開始前に buildSkillContext / buildSkillGenerationPrompt / skill.create(..., context) の3点を契約チェックとして固定し、packages/shared・apps/desktop/src/renderer・apps/desktop/src/main を同一 wave で突合する。ズレがあれば close-out 前に仕様と成果物（phase spec / artifacts）を同時修正する |
| [FB-SDK-07-2] Phase 1 で新規 IPC surface を定義する際に Preload API 経由が明記されない | Phase 1（要件定義）では新規 IPC surface を定義する場合、「Preload API 経由必須」を明記する。直接 ipcRenderer.on は禁止パターンとして記録する |
| [FB-SDK-07-4] Phase 1 で既存 API の命名パターンを確認せずに新規 API を命名し、Phase 3 で MINOR 指摘を受ける | Phase 1（要件定義）では既存の safeOn / safeInvoke 等の命名パターンを確認し、新規 API の命名規則一貫性を担保する。命名ドリフトは Phase 3 レビューゲートの MINOR 指摘の主要因となる |
[Feedback W1-02b-1] UI task の screenshot-plan.json が mode: "NON_VISUAL" のまま Phase 11 を迎えやすい |
UI コンポーネント変更タスクでは screenshot-plan.json 生成時に mode: "VISUAL" をデフォルトにする。phase11-capture-metadata.json の taskId が現行タスク ID と一致するか Phase 11 着手前に確認する（jq '.taskId' outputs/phase-11/phase11-capture-metadata.json） |
| [Feedback W1-02b-2] multi-step wizard 設計で「ステップ間の state ownership と引き渡し項目」が Phase 2 設計書に未記載 | Phase 2（設計）でウィザード / マルチステップ UI を設計する場合、「ステップ間 state 引き渡しテーブル」を必須セクションとして設ける。smartDefaults など推論値の反映タイミング（初回のみ / 都度上書き / ユーザー優先）は decision 欄で固定する |
[Feedback W1-02b-3] implementation-guide.md の callback 名・props 名が実装と一致していない（identifier drift） |
Phase 12 Task 12-6 で implementation-guide.md 内の識別子を現行コードで grep 確認する。スニペットは型定義・props interface から引用し、手書き snippets を避ける |
| [Feedback W1-02b-4] renderer UI コンポーネントで node-only パッケージを直接 import し、Vite browser bundle が runtime error になる | renderer コンポーネントでは node-only パッケージ（node-cron 等）を直接 import しない。cron/schedule 検証は browser-safe ユーティリティに切り出す。Phase 11 capture 前に「ブラウザで実際に route を開く smoke test」を必須にする |
[Feedback W0-RV-001] minLength / maxLength のテストケースで境界値文字列の実文字数を確認せずに誤った長さで書く（例: "十文字以上の目的" = 実際は 7 文字） |
テスト文字列を書く前に "...".length で実文字数を確認する。日本語の漢数字表記の意味と .length は別物。境界値テストは // length: N コメントを付けてから書く |
[Feedback SC-13-1] IPC surface 追加時に apps/desktop/src/preload/channels.ts の ALLOWED_INVOKE_CHANNELS への追記が漏れる |
IPC surface 追加タスクでは Phase 2 成果物のチェックリストに「ALLOWED_INVOKE_CHANNELS への追記」を必須項目として記載する。shared/ipc/channels.ts への定数追加だけでは Renderer から呼び出せない |
[Feedback SC-13-2] 公開 IPC メソッド名（verify(skillName, ...)）と内部エンジンメソッド名（verifySkill(skillDir)）が酷似し Phase 2 設計時に責務が不明確になる |
公開 surface と内部エンジンで名前が近い場合、Phase 2 成果物に「内部型 → 公開 DTO 変換表」と「解決レイヤ名称（例: resolveVerifySkillDir）」を必須セクションとして設ける |
[Feedback VSCPKR-01] JSDoc コメント内に */ を含む説明（例: ステップ値 */n）があると esbuild がコメント終端と誤認識しパースエラーになる |
cron 式や数式を JSDoc コメント内で説明する場合は */ を避け、* /n のようにスペースを挿入するか、コードブロック（```）形式で書く。@example タグ内の inline cron 式も同様 |
[Feedback VSCPKR-02] happy-dom 環境で vi.stubGlobal("window", ...) でウィンドウ全体を置き換えると React 内部の instanceof HTMLElement が常に false になり、コンポーネントテストが壊れる |
window.api などの Electron Preload API をモックする場合は Object.defineProperty(window, "api", { value: mockApi, writable: true }) を使う。vi.stubGlobal("window", ...) は使用禁止 |
| [FB-CRONVL-001] Phase 2 でサードパーティライブラリを採用する際に、複合フィールド（day-of-month × day-of-week）の組み合わせ動作（AND/OR semantics）を実測確認しないと、Phase 5 で設計変更が必要になり TDD の期待値を修正し直す手戻りが発生する | Phase 2 設計書の「ライブラリ選定」セクションに「複合フィールドの semantics 実測確認」を必須チェック項目として記載する。例: CronExpressionParser.parse("0 0 31 2 1") の next-execution 計算結果で AND/OR 判定を確認する。期待 semantics と一致しない場合は safe-side 判定（到達不能を常にエラー）への方針変更を Phase 2 で決定する |
[FB-CRONVL-002] renderer utility に opt-in フラグ（例: semantic?: boolean）を追加する場合、Phase 1 スコープで「UI 呼び出し経路は別タスク化する」を明示しないと、UI 統合の担当タスクが曖昧なまま積み残される |
Phase 1（要件定義）で opt-in フラグを設計する際は、「このフラグを UI から有効化するタイミングと担当タスク ID は別タスクで明示する」を scope out として明記する。NON_VISUAL タスクでは特に「将来の UI 統合経路 = 未タスク化候補」を Phase 1 成果物に書き残す |
[FB-TASK-01/02] testid 削除・改名後に describe.skip ブロック内の旧参照が残存し CI に検出されない（スキップ済みテストは実行されないため型エラーも発生しない） |
testid 削除タスクでは Phase 5 完了チェックとして grep -rn "<削除testid>" apps/ を実行し、describe.skip 内を含む全残存参照をゼロにする。同一 wave で削除しないと cleanup タスクが積み残される |
| [WEEKGRD-01] NON_VISUALタスクのPhase 11では、source-level PASSと環境ブロッカーを混在させて記録してしまい、後からブロッカーの性質が判断できなくなる | source-level PASSと環境ブロッカー（esbuild mismatch等）を別カテゴリで記録する。製品コードの問題と環境起因の問題は分離しないと、次回タスクで同じ混乱が起きる |
| [WEEKGRD-02] 純粋関数ガードの実装方針として「例外スロー」を選択してしまい、呼び出し元への影響が広がる | 純粋関数ガードのデフォルト戦略は「例外なし・無効値返却（空文字等）」とする。入力バリデーションは呼び出し元（UIレイヤ等）に委ね、関数自体は防御的な値返却に徹する |
[WEEKGRD-03] NON_VISUALタスクの ui-sanity-visual-review.md に非該当理由が明記されず、reviewerがNON_VISUAL判断の根拠を読み取れない |
NON_VISUALタスクでは ui-sanity-visual-review.md の冒頭に「NON_VISUAL宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |
| 漏れパターン | 防止方法 |
|---|---|
[UT-W3] implementation-guide.md が current contract（trackEvent → analyticsAdapter → analytics:send）ではなく旧方針（renderer-local no-op）のまま記述される |
Phase 12 Task 12-1 で implementation-guide.md を作成する前に trackEvent.ts の prod sink 分岐と analyticsAdapter.ts の存在を確認し、current contract を先に記録してから説明文を書く |
[UT-W3] artifacts.json / outputs/artifacts.json parity 未確認のまま Phase 12 を閉じる |
Phase 12 完了前に artifacts.json と outputs/artifacts.json の両ファイルを diff し、phase12_completed + phase13_blocked が同値であることを確認する |
[UT-W3] Phase 12 Task 12-2/12-3/12-6 で generate-index.js 実行を省略してインデックスが stale になる |
Task 12-2（システム仕様書更新）・Task 12-3（changelog 更新）・Task 12-6（compliance check）の完了後は node .claude/skills/aiworkflow-requirements/scripts/generate-index.js を必ず実行し、インデックス stale を防ぐ |
[UT-W3] shared 型を追加したのに types/index.ts / package index / consumer wiring のどれかが残り、Phase 12 が false complete になる |
shared 型追加タスクでは definition + types/index + package index + consumer wiring を同 wave で揃え、outputs/artifacts.json と root artifacts の parity も同時に確認する |
[UT-W3-HTTP] Phase 4 でガード条件（if (!url)）の全 falsy パターンを列挙せず、空文字 URL（TC-E04）が Phase 6 でしか検出されなかった |
ガード節を設計する際は undefined / null / "" / スペースのみの4パターンを同時に列挙し、!url が網羅するケースを Phase 4 テスト仕様に明記する |
| Step 1-C（関連タスクテーブル）を未実行 | spec-update-workflow.md の「確認すべきファイル」表を実行前に必ず読む |
| topic-map.md 未更新 | 仕様書に新規セクション追加時は必ず topic-map.md のエントリも追加 |
| documentation-changelog.md が不完全 | 全Step（1-A/1-B/1-C/Step 2）の結果を個別に明記する（「該当なし」も記録） |
system-spec-update-summary.md を未作成で完了扱い |
Phase 12成果物一覧と outputs/phase-12/ 実体を1対1で突合し、不足ファイルは完了前に作成する |
| LOGS.md が1ファイルのみ更新 | 必ず aiworkflow-requirements/LOGS.md と task-specification-creator/LOGS.md の両方 |
| 完了タスクセクションが簡略形式 | spec-update-workflow.md のテンプレート（テスト結果サマリー + 成果物テーブル）に従う |
artifacts.json と outputs/artifacts.json が不一致 |
Phase 12完了前に2ファイルを同期し、completed成果物の参照切れを0件にする |
| [FB-04] Phase 12 close-out で backlog ledger / completed ledger / lane index / workflow artifacts / skill artifacts の5点を同一waveで同期せず、タスク状態が二重化する | Step 1-A の開始時に三者同期チェックリストで5ファイルを1件ずつ突合し、同一ターンで一括更新する。更新後は validate-phase-output.js --phase 12 と diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator で整合を確認する |
設計タスクの workflow root を completed にしてしまう |
workflow root は implementation_ready、completed ledger は spec_created に分離する |
| Phase 10 MINOR指摘を未タスク化せず進行 | Phase 10レビュー前に unassigned-task-guidelines.md を読み、MINOR判定→未タスク化ルールを確認 |
| 未タスク検出レポートで0件判定のまま未修正 | Phase 10 MINOR指摘は必ず未タスク化の対象。「機能に影響なし」は不要判定の理由にならない |
task-workflow.md の未タスクリンクが参照切れ |
Step 1-E後に verify-unassigned-links.js を実行して ALL_LINKS_EXIST を確認する |
[Feedback 2] Phase 12 着手時に outputs/artifacts.json と phase spec の artifact 名が照合されない |
Phase 12 の 最初の作業として outputs/artifacts.json と各 phase-*.md に記載されたartifact名を1対1で突合し、不一致があれば着手前に修正する |
| [Feedback 3] Phase 11 の UI task / docs-only task 判定がずれる | Phase 1 で記録したタスク分類（UI task / docs-only task）を Phase 11 着手時に必ず参照する。分類が変わっていた場合は再判定を明示する |
[Feedback W0-01] shared 型追加で root @repo/shared に再エクスポートすると SkillCategory が衝突する |
新しい共有型は subpath export（例: @repo/shared/types/skillCreator）に閉じ、既存 root barrel は触らない。phase-12-documentation.md と system spec の両方で公開経路を明記する |
| [Feedback P0-09-U1-1] Phase 4 仕様書に private method テスト方針が未記載 | (facade as unknown as FacadePrivate) キャストと public callback 経由テストの2択を Phase 4 仕様書に必ず明記する |
[Feedback P0-09-U1-2] improve() フローの canUseTool 配線先（SDK callback vs applyImprovement()）が仕様書から読み取れない |
Phase 5 仕様書のタスク2に「canUseTool 適用可能範囲と制約」セクションを設け、llmAdapter.sendChat() 経由時は SDK callback 非適用と明記する |
| [Feedback BEFORE-QUIT-001] Phase 11 が非 visual task なのに実地操作を要求してしまう | Phase 11 では「実地操作不可」を明記し、自動テスト結果 + 既知制限リストを代替記録として残す |
| [Feedback BEFORE-QUIT-002] Phase 7 coverage が全ファイル一律指定だと局所検証の意図がぼやける | Phase 7 では coverage の対象範囲を明示し、変更したファイル/ブロック以外を対象外として書く |
| [Feedback BEFORE-QUIT-003] Phase 12 の system-spec update で workflow-local と global sync が混在する | documentation-changelog.md で workflow-local 同期と global skill sync を別ブロックで記録する |
| [Feedback 4] Phase 11 NON_VISUAL のとき manual-test-result.md の証跡メタが薄い | Phase 11 が NON_VISUAL の場合、manual-test-result.md のメタ情報に「証跡の主ソース（自動テスト名/件数）」と「スクリーンショットを作らない理由」を明記する。空メタでは reviewer が意図を読み取れない |
| [Feedback 5] Phase 7 の coverage 目標が広域指定のとき変更行の保護確認が曖昧になる | Phase 7 のカバレッジ目標が「全体 X%」など広域指定のとき、変更した関数/ブロックの line カバレッジと branch カバレッジの実測値を証跡に残す（例: applyWorkflowSnapshot 付近の line 100% / branch 100%） |
| [Feedback 6] ViewType を追加した際に navigation 契約・store 型・既存テストの3点更新が漏れる | store/types.ts（ViewType union）/ skillLifecycleJourney.ts（正規化関数・定数）/ renderView テスト を same-wave で更新し、ui-ux-navigation.md の ViewType テーブルも同時同期する。Phase 1 設計メモに「追加 ViewType: XYZ」を明示しておくと漏れが防げる |
| [FB-UI-02-1] Phase 9 QA で「ファイル削除」を PASS 基準にすると stub 化タスクが FAIL 扱いになる | Phase 9 の削除確認は「git delete されている OR export {} stub 化かつ live import ゼロのいずれか」を PASS とする。たとえば、廃止ファイルを stub 化した場合は grep -rn "import.*廃止ファイル名" src/ でゼロ件を証跡に残す |
[Feedback TASK-UI-04] 実装完了後に artifacts.json status が spec_created / in_progress のまま放置される |
実装 Phase（Phase 5 or 最終実装 Phase）完了時に complete-phase.js を必ず実行し、status を completed に更新する。実装完了と仕様書ステータス更新は同一 wave で行う（後回しは乖離蓄積の主因）。有効値: spec_created / in_progress / completed / phase12_completed |
[FB-DATAFLOW-001] SkillCreationContext 追加時に shared 型・renderer store・preload/main IPC の context bridge 同期が同一waveで更新されず、implementation-guide.md と実コードの dataflow が乖離する |
Phase 12 Task 12-1/12-2 の開始前に buildSkillContext / buildSkillGenerationPrompt / skill.create(..., context) の3点を契約チェックとして固定し、packages/shared・apps/desktop/src/renderer・apps/desktop/src/main を同一 wave で突合する。ズレがあれば close-out 前に仕様と成果物（phase spec / artifacts）を同時修正する |
[FB-FEEDBACK-001] LLM モード成功後に fetchSkills() の明示呼び出しを省略すると、スキル一覧がリアルタイム更新されず UX が壊れる。template モードは createSkill（agentSlice）内部で fetchSkills を呼ぶため自動解消されるが、LLM モードの handleExecutePlan は明示呼び出しが必要 |
handleExecutePlan の成功パス末尾に await fetchSkills() を追加し、失敗時は遷移を阻害しないよう独立した try/catch でswallow する。TC-FEEDBACK-001 のような LLM モード専用 regression test case を設けて再発を防ぐ |
| [FB-SDK-07-2] Phase 1 で新規 IPC surface を定義する際に Preload API 経由が明記されない | Phase 1（要件定義）では新規 IPC surface を定義する場合、「Preload API 経由必須」を明記する。直接 ipcRenderer.on は禁止パターンとして記録する |
| [FB-SDK-07-4] Phase 1 で既存 API の命名パターンを確認せずに新規 API を命名し、Phase 3 で MINOR 指摘を受ける | Phase 1（要件定義）では既存の safeOn / safeInvoke 等の命名パターンを確認し、新規 API の命名規則一貫性を担保する。命名ドリフトは Phase 3 レビューゲートの MINOR 指摘の主要因となる |
[Feedback W1-02b-1] UI task の screenshot-plan.json が mode: "NON_VISUAL" のまま Phase 11 を迎えやすい |
UI コンポーネント変更タスクでは screenshot-plan.json 生成時に mode: "VISUAL" をデフォルトにする。phase11-capture-metadata.json の taskId が現行タスク ID と一致するか Phase 11 着手前に確認する（jq '.taskId' outputs/phase-11/phase11-capture-metadata.json） |
| [Feedback W1-02b-2] multi-step wizard 設計で「ステップ間の state ownership と引き渡し項目」が Phase 2 設計書に未記載 | Phase 2（設計）でウィザード / マルチステップ UI を設計する場合、「ステップ間 state 引き渡しテーブル」を必須セクションとして設ける。smartDefaults など推論値の反映タイミング（初回のみ / 都度上書き / ユーザー優先）は decision 欄で固定する |
[Feedback W1-02b-3] implementation-guide.md の callback 名・props 名が実装と一致していない（identifier drift） |
Phase 12 Task 12-6 で implementation-guide.md 内の識別子を現行コードで grep 確認する。スニペットは型定義・props interface から引用し、手書き snippets を避ける |
| [Feedback W1-02b-4] renderer UI コンポーネントで node-only パッケージを直接 import し、Vite browser bundle が runtime error になる | renderer コンポーネントでは node-only パッケージ（node-cron 等）を直接 import しない。cron/schedule 検証は browser-safe ユーティリティに切り出す。Phase 11 capture 前に「ブラウザで実際に route を開く smoke test」を必須にする |
[Feedback W0-RV-001] minLength / maxLength のテストケースで境界値文字列の実文字数を確認せずに誤った長さで書く（例: "十文字以上の目的" = 実際は 7 文字） |
テスト文字列を書く前に "...".length で実文字数を確認する。日本語の漢数字表記の意味と .length は別物。境界値テストは // length: N コメントを付けてから書く |
[Feedback SC-13-1] IPC surface 追加時に apps/desktop/src/preload/channels.ts の ALLOWED_INVOKE_CHANNELS への追記が漏れる |
IPC surface 追加タスクでは Phase 2 成果物のチェックリストに「ALLOWED_INVOKE_CHANNELS への追記」を必須項目として記載する。shared/ipc/channels.ts への定数追加だけでは Renderer から呼び出せない |
[Feedback SC-13-2] 公開 IPC メソッド名（verify(skillName, ...)）と内部エンジンメソッド名（verifySkill(skillDir)）が酷似し Phase 2 設計時に責務が不明確になる |
公開 surface と内部エンジンで名前が近い場合、Phase 2 成果物に「内部型 → 公開 DTO 変換表」と「解決レイヤ名称（例: resolveVerifySkillDir）」を必須セクションとして設ける |
[Feedback VSCPKR-01] JSDoc コメント内に */ を含む説明（例: ステップ値 */n）があると esbuild がコメント終端と誤認識しパースエラーになる |
cron 式や数式を JSDoc コメント内で説明する場合は */ を避け、* /n のようにスペースを挿入するか、コードブロック（```）形式で書く。@example タグ内の inline cron 式も同様 |
[Feedback VSCPKR-02] happy-dom 環境で vi.stubGlobal("window", ...) でウィンドウ全体を置き換えると React 内部の instanceof HTMLElement が常に false になり、コンポーネントテストが壊れる |
window.api などの Electron Preload API をモックする場合は Object.defineProperty(window, "api", { value: mockApi, writable: true }) を使う。vi.stubGlobal("window", ...) は使用禁止 |
| [VSCPKR-03] Phase 4 でコンポーネントテストを設計する際に、テストで操作する入力が外部 props か内部 state かを Phase 2 で確認しておらず、TDD RED フェーズで「テストが通らない」問題が props/state の混同に起因することに気づかない | Phase 2（設計）で UI コンポーネントのモード管理方法を明記する（例: "isAdvancedMode は内部 state"）。Phase 4 仕様書に「テスト操作対象は internal state か external prop か」を明記し、TDD RED を書く前にコンポーネントの props interface と内部 useState を区別する |
| [FB-CRONVL-001] Phase 2 でサードパーティライブラリを採用する際に、複合フィールド（day-of-month × day-of-week）の組み合わせ動作（AND/OR semantics）を実測確認しないと、Phase 5 で設計変更が必要になり TDD の期待値を修正し直す手戻りが発生する | Phase 2 設計書の「ライブラリ選定」セクションに「複合フィールドの semantics 実測確認」を必須チェック項目として記載する。例: CronExpressionParser.parse("0 0 31 2 1") の next-execution 計算結果で AND/OR 判定を確認する。期待 semantics と一致しない場合は safe-side 判定（到達不能を常にエラー）への方針変更を Phase 2 で決定する |
[FB-CRONVL-002] renderer utility に opt-in フラグ（例: semantic?: boolean）を追加する場合、Phase 1 スコープで「UI 呼び出し経路は別タスク化する」を明示しないと、UI 統合の担当タスクが曖昧なまま積み残される |
Phase 1（要件定義）で opt-in フラグを設計する際は、「このフラグを UI から有効化するタイミングと担当タスク ID は別タスクで明示する」を scope out として明記する。NON_VISUAL タスクでは特に「将来の UI 統合経路 = 未タスク化候補」を Phase 1 成果物に書き残す |
[FB-TASK-01/02] testid 削除・改名後に describe.skip ブロック内の旧参照が残存し CI に検出されない（スキップ済みテストは実行されないため型エラーも発生しない） |
testid 削除タスクでは Phase 5 完了チェックとして grep -rn "<削除testid>" apps/ を実行し、describe.skip 内を含む全残存参照をゼロにする。同一 wave で削除しないと cleanup タスクが積み残される |
| [WEEKGRD-01] NON_VISUALタスクのPhase 11では、source-level PASSと環境ブロッカーを混在させて記録してしまい、後からブロッカーの性質が判断できなくなる | source-level PASSと環境ブロッカー（esbuild mismatch等）を別カテゴリで記録する。製品コードの問題と環境起因の問題は分離しないと、次回タスクで同じ混乱が起きる |
| [WEEKGRD-02] 純粋関数ガードの実装方針として「例外スロー」を選択してしまい、呼び出し元への影響が広がる | 純粋関数ガードのデフォルト戦略は「例外なし・無効値返却（空文字等）」とする。入力バリデーションは呼び出し元（UIレイヤ等）に委ね、関数自体は防御的な値返却に徹する |
[WEEKGRD-03] NON_VISUALタスクの ui-sanity-visual-review.md に非該当理由が明記されず、reviewerがNON_VISUAL判断の根拠を読み取れない |
NON_VISUALタスクでは ui-sanity-visual-review.md の冒頭に「NON_VISUAL宣言」（タスク種別・非視覚的理由・代替証跡）を明記する。空欄や略記はレビューアの混乱を招く |
[FB-IPC-SNAP-001] Electron ipcMain の snapshot test で vi.spyOn(ipcMain, "handle") を直接使うと、vi.hoisted タイミング問題で capture が不安定になる |
vi.hoisted(() => ({ mockIpcMainHandle: vi.fn() })) + vi.mock("electron", ...) + mockImplementation((ch) => { handles.push(ch) }) のパターンで実装する。vi.spyOn を ipcMain に直接適用する前提はずらすこと（UT-IPC-HANDLER-CI-001 Pitfall） |
[FB-IPC-SNAP-002] Phase 5 の「実行タスク」に --updateSnapshot の初回生成と既存スナップショットとの比較確認が別ステップとして明示されておらず、更新許可条件が曖昧になる |
test/CI ガード系タスクの Phase 5 に「初回スナップショット生成（--updateSnapshot を明示許可）」と「既存スナップショットとの diff 確認（変更前後の内容比較）」を別ステップとして記載する。更新が許可される条件（新規追加・意図的チャンネル追加）と禁止される条件（未承認のチャンネル増減）を明文化する |
[FB-CANCEL-004-1] AbortSignal のような「partial fix しやすい契約ズレ」（Renderer が signal を初期化したが consumer wiring が未完）を完了判定前に発見できず、次タスクで同じ課題が再浮上する |
Phase 10 レビュー時に「実装済みの contract が consumer side まで通っているか」を確認する。Renderer/Store/API の3層で断絶がある場合は「partial fix」と明記し、残存部分を residual issue として unassigned-task-detection.md に格下げ登録する。格下げテンプレート: 状態: partial_fix / 残存部位: consumer wiring / 対象ファイル: <path> |
[FB-CANCEL-004-2] unassigned-task-detection.md に関連済みタスクとの差分確認欄がなく、重複起票が起きやすい |
unassigned-task-detection.md のテンプレートに「関連タスク差分確認」セクションを設け、既存タスク ID（TASK-SC-ABORT-SIGNAL-* 等）との重複チェックを Phase 12 着手前に実施する。重複している場合は「統合先タスク ID」を明記して未タスク登録を省略可能とする |
UT-STORE-HOOKS-COMPONENT-MIGRATION-001の経験に基づく（2026-02-12）
| Tips | 説明 |
|---|---|
| 事前に空欄チェックリストを作成 | documentation-changelog.mdにStep 1-A〜1-D + Step 2の各欄を空欄で事前作成し、逐次消化する |
| spec-update-workflow.mdを常に参照 | Phase 12開始時に必ず spec-update-workflow.md を開き、チェックリストを確認 |
| 「全Step確認前に完了と記載しない」厳守 | P4パターン。全Stepの結果を個別に記録してから「Phase 12完了」とする |
| LOGS.md/SKILL.md は4ファイル更新 | aiworkflow-requirements/LOGS.md, task-specification-creator/LOGS.md, aiworkflow-requirements/SKILL.md, task-specification-creator/SKILL.md |
| topic-map.md再生成はセクション変更時も | 新規追加だけでなく、セクション更新・削除時も node .claude/skills/aiworkflow-requirements/scripts/generate-index.js と node .claude/skills/task-specification-creator/scripts/generate-index.js --workflow docs/30-workflows/{{FEATURE_NAME}} --regenerate を実行 |
worktree環境でも .claude 正本を実更新する |
worktree を理由に LOGS.md / SKILL.md / backlog / workflow の更新を先送りしない。.agents/skills/ は rsync / diff で mirror parity を確認する |
| 並列エージェント完了後はファイルシステムで検証 | P43/P59対策。エージェントがコンテキスト制限で応答不能になった場合、git diff --stat + ls outputs/phase-*/ + artifacts.json のPhaseステータスで成果物の存在を確認する |
NON_VISUAL判定時は screenshots/.gitkeep を削除する |
screenshots/ ディレクトリが空（PNG 0件）のまま残るとvalidator errorになる。NON_VISUAL判定で実スクリーンショットが不要な場合は screenshots/.gitkeep を削除してディレクトリごと除外する |
worktree作成後は pnpm install を確認する |
esbuild host/binary version drift により Vitest 起動前に停止することがある。worktree作成後は必ず pnpm install を実行してバイナリの整合を確保する |
complete-phase.js でPhase完了ステータスを更新PR作成は自動実行しない。必ずユーザーの明示的な許可を得てから実行すること。
📖 references/commands.md - コマンド一覧
| Task | 完了条件 | 詳細 |
|---|---|---|
| Task 12-1 | implementation-guide.md が Part 1/2 を満たす |
references/phase-12-documentation-guide.md |
| Task 12-2 | Step 1 と Step 2 の判定が記録される | references/spec-update-workflow.md |
| Task 12-3 | documentation-changelog.md と artifacts が同期される |
references/spec-update-validation-matrix.md |
| Task 12-4 | 0件でも unassigned-task-detection.md を出し、current/baseline を分離して記録する |
references/unassigned-task-guidelines.md |
| Task 12-5 | 改善点なしでも skill-feedback-report.md を出す |
references/patterns-phase12-sync.md |
| Task 12-6 | phase12-task-spec-compliance-check.md を root evidence として残す |
references/patterns-phase12-sync.md |
| Phase 13 | commit と PR は user の明示承認後だけ | references/review-gate-criteria.md |
UI/UX 実装を含む task では Phase 11 で screenshot と Apple UI/UX 視覚検証を行う。手順は references/phase-11-screenshot-guide.md と references/screenshot-verification-procedure.md を使う。
| 観点 | aiworkflow-requirements 側の参照先 |
|---|---|
| セキュリティ | security-*.md |
| UI/UX | ui-ux-*.md |
| アーキテクチャ | architecture-*.md |
| API/IPC | api-*.md |
| データ整合性 | database-*.md |
| エラーハンドリング | error-handling.md |
| インターフェース | interfaces-*.md |
Electron desktop task では Renderer、Main、IPC、Preload、ローカルストレージの境界を都度明記する。詳細は references/quality-standards.md を参照。
node scripts/validate-phase-output.js docs/30-workflows/{{FEATURE_NAME}}
node scripts/verify-all-specs.js --workflow docs/30-workflows/{{FEATURE_NAME}}
node ../skill-creator/scripts/quick_validate.js .claude/skills/task-specification-creator
node ../skill-creator/scripts/validate_all.js .claude/skills/task-specification-creator
diff -qr .claude/skills/task-specification-creator .agents/skills/task-specification-creator
node scripts/log-usage.js --result success --phase "Phase {{N}}"
Phase 12 では追加で detect-unassigned-tasks.js、audit-unassigned-tasks.js、verify-unassigned-links.js、validate-phase12-implementation-guide.js を実行する。
outputs/phase-N/ を phase ごとに実体化し、artifacts.json と同時更新する。references/ へ逃がし、SKILL.md は入口に保つ。implementation-guide、system-spec-update-summary、documentation-changelog、unassigned-task-detection、skill-feedback-report、phase12-task-spec-compliance-check を必ず揃える。definition / types/index / package index / consumer wiring を同 wave で同期する。retry は formData 保持 + answers リセット、start over は全 state クリアが標準パターン。useEffect(() => { setInternal(prop) }, [prop]) で親から子への再同期ポイントを明示する必要がある。Phase 4 テスト仕様に「props 変更 → internal state 再同期」のテストケースを必須化する。Record<string, unknown> 等）を扱う場合、Phase 2 設計でシャロー/ディープマージ戦略を明示すること。配列・null・undefined の扱いもマージルールとして設計書に記載する。IPC 経由の設定更新は plain object のみに制限し、__proto__ / constructor / prototype を無視して prototype pollution を防ぐ。発見元: UT-FIX-STORE-SETTINGS-DEEP-MERGE-001.agents 側だけ先に更新して canonical root を残すこと。outputs/ を後回しにして phase 完了だけ先に付けること。current と baseline の監査結果を混ぜること。| Version | Date | Changes |
|---|---|---|
| v10.09.60 | 2026-04-22 | UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 skill-feedback 反映: Phase 12 Task 2 に Step 1-D（EVALS.json taskMetrics 追記を Phase 12 必須ステップとして標準化）を追加。Phase 7 実行表に [EVALS-DOC-001]（docs-only タスクでは totalTests=0 / avgCoverage=0 で固定し「対象コードなし（N/A）」として記録するルール）を追記。LOGS.md 同波更新。 |
| v10.09.59 | 2026-04-21 | UNASSIGNED-EVALS-SPEC-QUALITY-INSIGHTS-DOCUMENT-001 close-out sync: aiworkflow-requirements/references/evals-schema-spec.md §6 qualityInsights 定義を実装実態（タスク ID キー辞書）に修正。docs-only タスク Phase 1-12 all PASS（NON_VISUAL / mirror sync 差分ゼロ / AC-1〜7 全達成）。task-specification-creator/EVALS.json の taskMetrics に本タスク完了エントリを追加（completedPhases=12 / totalTests=0 / avgCoverage=0 / systemSpecsUpdated=2 / unassignedTasksDetected=0）。 |
| v10.09.58 | 2026-04-20 | TASK-SC-CANCEL-LOGS-SYNC-001 review-closeout sync: Phase 11 manual-test-result.md を 4 セクション正本へ是正し、Phase 12 implementation-guide.md に Part 1/Part 2/視覚証跡 を追加、phase12-task-spec-compliance-check.md の future tense を除去。子 task root index.md / artifacts.json / outputs/artifacts.json を Phase 1-12 completed / Phase 13 blocked へ同期し、aiworkflow-requirements completed ledger 追記、unassigned task 2 件起票、.agents mirror parity を同波で閉じる手順を current facts に反映。 |
| v10.09.57 | 2026-04-19 | TASK-EVALS-CONSUMER-AUDIT-001 PROPOSAL-TSC-01〜05 反映: (1) PROPOSAL-TSC-01: references/phase-template-audit-task.md 新設（NON_VISUAL / 監査タスク向け Phase 再解釈マップ、primary evidence 棲み分け、完了ステータス判断、canonical vs 必須6成果物区別、PR12-R1〜R5 落とし穴集約、185行）。(2) PROPOSAL-TSC-02: phase-12-documentation-guide.md Task 12-1 直下に UI/UX変更なしのため Phase 11 スクリーンショット不要 固定記載ルールと primary evidence = manual-test-result.md を明記。phase-template-phase11.md にタスク種別判定テーブル NON_VISUAL 行追加 + NON_VISUAL / 監査タスク分岐セクション新設。(3) PROPOSAL-TSC-03: phase-template-phase12.md 出力テンプレに canonical N 成果物 vs 必須 6 成果物の分離 + P12-R2 リスク対策ルール追加。(4) PROPOSAL-TSC-04: 未タスク配置先決定フロー（If-Then-Else ASCII）を phase-template-phase12.md §P38 再発防止セクションに集約。(5) PROPOSAL-TSC-05: phase-template-phase12.md の Task 12-1〜12-5 誤植行を削除し Task 12-1〜12-6 に統一。SKILL.md Anchors phase templates に audit-task.md を追加。LOGS.md 同波更新。 |
| v10.09.57 | 2026-04-19 | TASK-LOGS-ARCHIVE-POLICY-001 skill-feedback 反映: docs-only タスクへの Phase 13 フレームワーク適用が機能確認済み。Phase 6〜9（テスト拡充・カバレッジ・リファクタリング・QA）の docs-only 向け読み替え定義が各 Phase に分散しているため、docs-only 専用テンプレートの新設を検討項目として記録。NON_VISUAL Phase 11 の証跡を manual-test-result.md チェックリストで代替するパターンを references/ に追記予定。 |
| v10.09.57 | 2026-04-19 | TASK-AGENTS-SKILLS-FULL-SYNC-001 impl-spec-to-skill-sync: 検証コマンドに bash .claude/scripts/verify-skills-parity.sh と bash .claude/scripts/sync-skills-mirror.sh を追加（pre-push hook と同一ロジック）。「worktree環境でも .claude 正本を実更新する」行を書き換え、sync-skills-mirror.sh による同期と verify-skills-parity.sh による parity 0 確認を明示。避けるべきことに「pre-push を --no-verify でスキップ」を追加。 |
| v10.09.56 | 2026-04-18 | UT-IPC-HANDLER-CI-001 skill-feedback 反映: 「Phase 12 実行時によくある漏れ」テーブルに [FB-IPC-SNAP-001]（Electron ipcMain snapshot test で vi.spyOn 直接適用が不安定になる / vi.hoisted + vi.mock パターンを使う）・[FB-IPC-SNAP-002]（Phase 5 に --updateSnapshot 初回生成と比較確認を別ステップとして明示する）を追記。LOGS.md 2ファイル同波更新。 |
| v10.09.55 | 2026-04-17 | TASK-UT-9I-001 Phase-12 検証完了: Phase-12成果物全6ファイルPASS確認。implementation-guide.md / system-spec-update-summary.md / documentation-changelog.md / unassigned-task-detection.md / skill-feedback-report.md / phase12-task-spec-compliance-check.md の存在・内容を検証し全87項目PASS。Phase 11 BLOCKED（API_KEY未設定）でも Phase 12 ドキュメントは作成可能な非依存性を記録。 |
| v10.09.53 | 2026-04-16 | TASK-LLM-MOD-05-RENDERER-DESC-DISPLAY current facts sync: Phase 11 screenshot canonical 名を inline-model-selector-description-hidden.png / inline-model-selector-tooltip-visible.png に統一し、phase11-capture-metadata.json / manual-test-result.md / implementation-guide.md / completed ledger を同波で更新。TASK-LLM-MOD-05 completed 化に合わせ、Phase 12 実行時によくある漏れ に [FB-VISUAL-CAP-001] を追加。 |
| v10.09.52 | 2026-04-16 | TASK-SC-PLAN-CONNECT-GENERATE-SKILL-MD-001 phase 12 close-out sync: .claude canonical を先に更新し、.agents mirror を同内容で追従する接続順序を固定。LOGS.md に 2026-04-16 の close-out sync を追記し、Phase 12 current facts を最新化。 |
| v10.09.52 | 2026-04-16 | TASK-SC-LLM-PURPOSE-WIRE-001 phase 12 close-out sync: Phase 2 で Result<T,E> の success / data 判別子と @repo/shared/services/llm/types alias を先に固定しないと、旧 TC-04 の影響を見落としやすいことを feedback 化。Phase 12 の 6 成果物と LOGS.md 2ファイル同波更新を記録。 |
| v10.09.50 | 2026-04-15 | TASK-SC-IMP-CREATE-WORKFLOW-001 phase 12 close-out sync: Phase 12 の 6 成果物と current facts を同波で固定し、outputs/artifacts.json parity、63件 Green、screenshot N/A を反映。runCreateWorkflow の戻り値観測を guard する方針と、planned wording の直書き排除を反映。 |
| v10.09.50 | 2026-04-15 | UT-SKILL-WIZARD-NOTION-SPECIAL-CASE-ELIMINATE-001 フィードバック反映: SemanticLabelEntry / resolveLabelEntry() / raw fallback 保持を current facts に追加し、Phase 12 実行時によくある漏れ に [FB-NOTION-001] を追加。 |
| v10.09.46 | 2026-04-13 | TASK-UI-SCHEDULE-CRON-MONTHLY-GUARD-001 フィードバック反映: (1) Number.isInteger ガードを先頭に置くパターンを標準化 (2) 双方向ガード（converter + parser）セット実装を推奨事項に追加 (3) switch-case ガードのブロック構文対称パターンを記録 |
| v10.09.22〜v10.09.33 | 2026-03-04〜2026-04-03 | 詳細履歴はアーカイブへ移管済み。内容は LOGS.md / references/logs-archive-2026-march.md を参照 |
補足: v9.89.0 以前の履歴は
LOGS.mdに保持（監査証跡を維持）。
詳細な履歴と usage log は LOGS.md と references/logs-archive-index.md を参照。
