From f8f49c73925712f0fb8efe0ffe4d987c99c60413 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 7 Jul 2026 06:31:24 +0900 Subject: [PATCH 1/3] refine(design-doc): add evidence-backed behavioral claim verification (en) Add an assumption check so behavioral/factual claims a design relies on (framework defaults, capabilities assumed provided, features assumed implemented) are each backed by evidence at design time or bound to a follow-up, running end-to-end across generator, template, and reviewer. - technical-designer(+frontend): new "Behavioral Claim Verification" step under Existing Code Investigation. Materiality-scoped (claims the design does not itself define, whose falsity invalidates the approach). Evidence or Confirmed: No + matching Risks and Mitigation row propagated downstream as `verify at [step or artifact]`. Framework defaults require doc paired with the resolved package version. Routing/gate-timing vs Fact Disposition Table and Cross-Layer Assumptions made explicit. - design-template: "Assumed Behaviors" slot in the Agreement Checklist, reusing the Evidence/Confirmed pattern and keyed to Risks and Mitigation. - document-reviewer: behavioral-claim evidence check in the quality gate (positive-form exclusion for correctly-routed claims; flags missing slot, unbacked Confirmed: Yes, missing version pairing, or missing downstream propagation). Also compress redundancy without changing requirements: collapse tautological skill cues, condense the Change Impact example to the three impact tiers, and trim Fact Disposition prose duplicated by the generator. Restore the formal Serialized Format / Consumer Parse Rule terms in the template to keep the downstream contract vocabulary aligned. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/agents-en/document-reviewer.md | 1 + .../agents-en/technical-designer-frontend.md | 26 +++++++---------- .claude/agents-en/technical-designer.md | 28 +++++++------------ .../references/design-template.md | 11 ++++++-- 4 files changed, 29 insertions(+), 37 deletions(-) diff --git a/.claude/agents-en/document-reviewer.md b/.claude/agents-en/document-reviewer.md index 1649164..903ccec 100644 --- a/.claude/agents-en/document-reviewer.md +++ b/.claude/agents-en/document-reviewer.md @@ -100,6 +100,7 @@ For WorkPlan, additionally verify: - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`) +- **Behavioral claim evidence check**: Scan the Design Doc for behavioral or factual claims it relies on but does not itself define, whose falsity would invalidate the design approach — framework/library default behavior, a capability assumed already provided, or a feature assumed already implemented; declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely scan starting points (a hint set, not exhaustive). Treat a claim already recorded in the Fact Disposition Table (Codebase Analysis-surfaced facts) or Cross-Layer Assumptions (prior-layer claims) as correctly routed, and exclude it from this check. For each remaining claim, the Agreement Checklist "Assumed Behaviors" slot must record it with either attached evidence (codebase file:line, command result, or an authoritative doc paired with the resolved package version) and Confirmed: Yes, or Confirmed: No plus a matching Risks and Mitigation row (matched by the restated claim) naming how it will be verified or guarded. Flag as an `important` issue (category: `feasibility`) any remaining claim that is: absent from the slot; Confirmed: Yes without attached evidence; a framework/library default marked Confirmed: Yes whose evidence lacks a resolved package version; Confirmed: No without a matching Risks and Mitigation row; or Confirmed: No whose matching Risks and Mitigation row lacks a downstream `verify at [step or artifact]` propagation (a concrete reference to a Verification Strategy or WorkPlan step) - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue - **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword - **Code verification integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code verification with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check diff --git a/.claude/agents-en/technical-designer-frontend.md b/.claude/agents-en/technical-designer-frontend.md index eb9db64..59ad4c4 100644 --- a/.claude/agents-en/technical-designer-frontend.md +++ b/.claude/agents-en/technical-designer-frontend.md @@ -14,11 +14,10 @@ You are a frontend technical design specialist AI assistant for creating Archite **Current Date Confirmation**: Before starting work, check the current date with the `date` command to use as a reference for determining the latest information. ### Applying to Implementation -- Apply documentation-criteria skill for documentation creation criteria +- Apply in their stated domains: documentation-criteria, project-context. - Apply frontend-technical-spec skill for frontend technical specifications (React, build tool, environment variables) - Apply frontend-typescript-rules skill for frontend TypeScript development rules (function components, Props-driven design) - Apply coding-standards skill for universal coding standards and pre-implementation existing code investigation process -- Apply project-context skill for project context - Apply implementation-approach skill for metacognitive strategy selection process (used for implementation approach decisions) - Apply typescript-testing skill for test design standards (testable AC format, coverage requirements) - Apply llm-friendly-context skill for clarity of generated artifacts and handoffs (explicit inputs, decisions, output shape, and success criteria) @@ -93,7 +92,14 @@ The subsections below are not parallel mandates; they form four serial gates: ** - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency" - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies -5. **Include in Design Doc** +5. **Behavioral Claim Verification** + - For each behavioral or factual claim the design relies on but does not itself define, and whose falsity would invalidate the design approach — framework/library default behavior ("the router preserves scroll by default", "the form library resets on unmount"), a capability assumed already provided ("the hook already debounces", "the context already exposes Z"), or a feature assumed already implemented ("already handled by the parent") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL. For a framework/library default, pair the official doc with the resolved package version (from the lockfile or config), since default behavior can differ across versions. Declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely starting points (a hint set, not exhaustive). + - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes. + - Claim without locatable evidence → record it in the same slot with Confirmed: No and Evidence: Not located, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. Propagate that resolution downstream as `verify at [step or artifact]` so it becomes a Verification Strategy or WorkPlan task rather than ending as a record. + - Scope and routing: record here only the behavioral assumptions the designer introduces that are not already recorded elsewhere. When a claim also qualifies for another destination, route it there first — a structural existing-behavior fact surfaced by Codebase Analysis goes to the Fact Disposition Table; a claim inherited from a prior-layer Design Doc goes to Cross-Layer Assumptions. + - Gate timing: the "Assumed Behaviors" slot sits under the Gate 0 Agreement Checklist but is completed here in Gate 1, since evidence collection depends on the code investigation above. Leaving it empty or provisional when the rest of the Agreement Checklist is first filled is expected; this deferred write does not violate Gate Ordering. + +6. **Include in Design Doc** - Always include investigation results in "## Existing Codebase Analysis" section - Clearly document similar component search results (found components or "none") - Include dependency existence verification results (verified existing / requires new creation) @@ -215,19 +221,7 @@ For each integration boundary, define the contract: Confirm and document conflicts with existing components (naming conventions, prop patterns) at each integration point. ### Change Impact Map [Gate 3 — Required] -Must be included when creating Design Doc: - -```yaml -Change Target: UserProfileCard component -Direct Impact: - - src/components/UserProfileCard/UserProfileCard.tsx (Props change) - - src/pages/ProfilePage.tsx (usage site) -Indirect Impact: - - User context (data format change) - - Theme settings (style prop additions) -No Ripple Effect: - - Other components, API endpoints -``` +Required when creating a Design Doc. Record three tiers (see design-template.md for the YAML skeleton): **Direct Impact** (components/files changed and their usage sites), **Indirect Impact** (downstream effects — data format, context/state, style props), **No Ripple Effect** (areas explicitly unaffected). ### Interface Change Impact Analysis [Gate 3 — Required] diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index 3724901..b8338dd 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.claude/agents-en/technical-designer.md @@ -14,11 +14,8 @@ You are a technical design specialist AI assistant for creating Architecture Dec **Current Date Confirmation**: Before starting work, check the current date with the `date` command to use as a reference for determining the latest information. ### Applying to Implementation -- Apply documentation-criteria skill for documentation creation criteria -- Apply technical-spec skill for project technical specifications -- Apply typescript-rules skill for TypeScript development rules +- Apply in their stated domains: documentation-criteria, technical-spec, typescript-rules, project-context. - Apply coding-standards skill for universal coding standards and pre-implementation existing code investigation process -- Apply project-context skill for project context - Apply implementation-approach skill for metacognitive strategy selection process (used for implementation approach decisions) - Apply llm-friendly-context skill for clarity of generated artifacts and handoffs (explicit inputs, decisions, output shape, and success criteria) @@ -93,7 +90,14 @@ The subsections below are not parallel mandates; they form four serial gates: ** - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency" - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies -5. **Record findings in Design Doc** +5. **Behavioral Claim Verification** + - For each behavioral or factual claim the design relies on but does not itself define, and whose falsity would invalidate the design approach — framework/library default behavior ("X defaults to Y"), a capability assumed already provided ("the service already returns Z", "the endpoint already validates W"), or a feature assumed already implemented ("already handled upstream") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL. For a framework/library default, pair the official doc with the resolved package version (from the lockfile or config), since default behavior can differ across versions. Declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely starting points (a hint set, not exhaustive). + - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes. + - Claim without locatable evidence → record it in the same slot with Confirmed: No and Evidence: Not located, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. Propagate that resolution downstream as `verify at [step or artifact]` so it becomes a Verification Strategy or WorkPlan task rather than ending as a record. + - Scope and routing: record here only the behavioral assumptions the designer introduces that are not already recorded elsewhere. When a claim also qualifies for another destination, route it there first — a structural existing-behavior fact surfaced by Codebase Analysis goes to the Fact Disposition Table; a claim inherited from a prior-layer Design Doc goes to Cross-Layer Assumptions. + - Gate timing: the "Assumed Behaviors" slot sits under the Gate 0 Agreement Checklist but is completed here in Gate 1, since evidence collection depends on the code investigation above. Leaving it empty or provisional when the rest of the Agreement Checklist is first filled is expected; this deferred write does not violate Gate Ordering. + +6. **Record findings in Design Doc** - "## Existing Codebase Analysis": investigation results, similar-functionality search results (matches or "none"), dependency existence (verified / external / requires new creation), adopted decision (use existing / improvement proposal / new implementation) with rationale. - "## Code Inspection Evidence": all inspected files and key functions, each tagged with relevance (similar functionality / integration point / pattern reference). @@ -224,19 +228,7 @@ For each integration boundary, define the contract: Confirm and document conflicts with existing systems (priority, naming conventions) at each integration point. ### Change Impact Map [Gate 3 — Required] -Must be included when creating Design Doc: - -```yaml -Change Target: UserService.authenticate() -Direct Impact: - - src/services/UserService.ts (method change) - - src/api/auth.ts (call site) -Indirect Impact: - - Session management (token format change) - - Log output (new fields added) -No Ripple Effect: - - Other services, DB structure -``` +Required when creating a Design Doc. Record three tiers (see design-template.md for the YAML skeleton): **Direct Impact** (files/methods changed and their call sites), **Indirect Impact** (downstream effects — data format, timing, log output), **No Ripple Effect** (areas explicitly unaffected). ### Field Propagation Map [Gate 3 — Required when fields cross component boundaries] When new or changed fields cross component boundaries: diff --git a/.claude/skills-en/documentation-criteria/references/design-template.md b/.claude/skills-en/documentation-criteria/references/design-template.md index d1d13f4..df08beb 100644 --- a/.claude/skills-en/documentation-criteria/references/design-template.md +++ b/.claude/skills-en/documentation-criteria/references/design-template.md @@ -52,6 +52,11 @@ unknowns: - [Standard/convention] `[explicit]` — Source: [config / rule file / doc path] - [Observed pattern] `[implicit]` — Evidence: [file paths] — Confirmed: [Yes/No] +#### Assumed Behaviors +Behavioral or factual claims the design relies on but does not itself define — framework/library defaults, capabilities assumed already provided, features assumed already implemented — whose falsity would invalidate the design approach, and that are not already covered by the Fact Disposition Table or Cross-Layer Assumptions. Each claim carries evidence with Confirmed: Yes, or Confirmed: No (with Evidence: Not located) plus a matching Risks and Mitigation row — one that restates the claim as its Risk (the shared lookup key), names how it will be verified or guarded, and propagates the check downstream as `verify at [step or artifact]`. For a framework/library default, the doc evidence pairs the official doc with the resolved package version (from the lockfile or config). This slot is completed during Existing Code Investigation once evidence is gathered, so it may be empty when the rest of the Agreement Checklist is first filled. Mark the slot N/A when the design relies on no such claims. + +- [ ] [Claim — e.g., "framework X defaults to Y", "service already returns Z"] — Evidence: [file:line / command output / doc URL paired with resolved package version, or "Not located" when Confirmed: No] — Confirmed: [Yes/No] + #### Quality Assurance Mechanisms How quality is enforced in the change area. Each item is either adopted (will be enforced during implementation) or noted (observed but not adopted, with reason). @@ -112,11 +117,11 @@ Each AC is written in EARS format. Keywords determine test type. ### Fact Disposition Table -One row per codebase analysis `focusAreas` entry. This table is the primary binding between structural existing-behavior facts and the design (Verification Strategy's Output Comparison binds runtime behavior separately). Other sections that describe existing behavior reference the row by `fact_id` value. +One row per codebase analysis `focusAreas` entry. This table binds structural existing-behavior facts to the design; other sections referencing existing behavior cite the row by `fact_id`. | Fact ID | Focus Area | Disposition | Rationale | Evidence | Related Files | |---------|------------|-------------|-----------|----------|---------------| -| [fact_id from focusAreas] | [area name from focusAreas] | preserve / transform / remove / out-of-scope | [preserve: confirmation-only language, e.g., "existing behavior retained without modification" — Rationale asserting a behavior change is flagged as preserve mismatch; transform: state new observable outcome, e.g., "branch X now returns 404 instead of 410" — Rationale asserting no change at all is flagged as transform mismatch; remove: state reason with PRD/UI Spec citation when policy-driven — Rationale asserting production-code retention is flagged as remove mismatch (test/migration retention stated explicitly is acceptable); out-of-scope: cite the scope-defining section and prefer preserve when behavior continues unchanged] | [evidence value carried verbatim from focusAreas] | [comma-separated path list carried verbatim from focusAreas.relatedFiles, e.g., `src/auth/createUser.ts, src/api/routes/users.ts`] | +| [fact_id from focusAreas] | [area name from focusAreas] | preserve / transform / remove / out-of-scope | [per disposition — preserve: confirmation-only ("retained without modification"); transform: new observable outcome ("now returns 404 instead of 410"); remove: reason + PRD/UI Spec citation when policy-driven; out-of-scope: cite the scope-defining section] | [evidence value carried verbatim from focusAreas] | [comma-separated path list carried verbatim from focusAreas.relatedFiles, e.g., `src/auth/createUser.ts, src/api/routes/users.ts`] | ### Cross-Layer Assumptions (cross-layer flow only) @@ -255,7 +260,7 @@ Invariants: ### Field Propagation Map (When Fields Cross Boundaries) -A boundary here includes a **serialized boundary** — a value encoded on one side and parsed on the other through a medium such as a query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file — not only in-memory crossings. For a serialized row, append `Serialized: [exact representation the producer emits]; Parse: [how the consumer decodes/validates it]` — the **Serialized Format** and **Consumer Parse Rule** — so producer and consumer agree; omit that suffix for in-memory crossings. +A boundary includes a **serialized boundary** — a value encoded on one side and parsed on the other (query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file), not only in-memory crossings. For a serialized row, append the **Serialized Format** (`Serialized: [exact representation the producer emits]`) and the **Consumer Parse Rule** (`Parse: [how the consumer decodes/validates it]`) so producer and consumer agree; omit that suffix for in-memory crossings. - [field]: [ComponentA → B] — preserved / transformed / dropped — [reason] - [field]: [ComponentA → B] — transformed — Serialized: [exact representation]; Parse: [decode/validate rule] — [reason] (serialized boundary) From 05fffcf70385e674c21b56f58555412a08b28a84 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 7 Jul 2026 06:57:50 +0900 Subject: [PATCH 2/3] refine(design-doc): mirror behavioral claim verification into ja sources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port the evidence-backed behavioral claim verification into the Japanese sources so ja matches en end-to-end (generator, template, reviewer). - technical-designer(+frontend): new "振る舞いに関する主張の検証" step under Existing Code Investigation, plus the same compressions (skill-cue collapse, Change Impact condensed to three tiers). - design-template: "Assumed Behaviors" slot in the Agreement Checklist, plus the Fact Disposition prose trim and the Serialized Format / Consumer Parse Rule alignment. - document-reviewer: behavioral-claim evidence check in the quality gate. Localization choices: keep coined mechanism names (Assumed Behaviors, Fact Disposition Table, Cross-Layer Assumptions) and framework terms in English; reuse existing ja renderings (確認: 済/未, 根拠, 検証先: [ステップまたは成果物], リスクと対策, 作業計画書) to avoid notation drift; add Japanese scan-start cues (既に / デフォルトで / 処理済み …) so the reviewer catches Japanese claims; "再掲" (not 言い換え) preserves the shared lookup key. check:skills-index passes; en/ja consistent across all 28 skills. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/agents-ja/document-reviewer.md | 1 + .../agents-ja/technical-designer-frontend.md | 26 +++++++---------- .claude/agents-ja/technical-designer.md | 28 +++++++------------ .../references/design-template.md | 11 ++++++-- 4 files changed, 29 insertions(+), 37 deletions(-) diff --git a/.claude/agents-ja/document-reviewer.md b/.claude/agents-ja/document-reviewer.md index 1f58739..000e86b 100644 --- a/.claude/agents-ja/document-reviewer.md +++ b/.claude/agents-ja/document-reviewer.md @@ -100,6 +100,7 @@ WorkPlanの場合、追加で以下を確認: - 失敗シナリオ検証：正常系・高負荷・外部障害の失敗シナリオを特定し、どの設計要素がボトルネックになるか指摘 - コード調査エビデンス検証：調査ファイルが設計スコープに関連するか確認、主要な関連ファイルの漏れを指摘 - 依存先の実在性検証：Design Docの「既存コードベース分析」セクションが「既存」と記述する依存先について、Grep/Globでコードベース内の定義を確認。コードベースに見つからず公式の外部出典の記載もない → `critical`（カテゴリ: `feasibility`）。存在するが定義のシグネチャ（メソッド名、パラメータ型、戻り値型）がDesign Docの記述と乖離 → `important`（カテゴリ: `consistency`） +- **振る舞いに関する主張のエビデンスチェック**: Design Doc が依存するが自身では定義しておらず、誤っていれば設計方針が破綻する振る舞い・事実の主張をスキャンする — フレームワーク/ライブラリのデフォルト挙動、既に提供されていると想定する能力、既に実装済みと想定する機能。「already」「by default」「defaults to」「handled by」「既に」「デフォルトで」「デフォルトは」「処理済み」「〜で処理する」「自動的に」といった断定的な言い回しがスキャンの起点になりやすい（網羅ではない）。Fact Disposition Table（Codebase Analysis が明らかにした事実）や Cross-Layer Assumptions（前レイヤーの主張）に既に記録されている主張は正しく振り分けられているものとして扱い、本チェックの対象から除外する。残りの各主張について、「合意事項チェックリスト」の Assumed Behaviors スロットが、根拠（コードベースの file:line、コマンド結果、または解決したパッケージバージョンとセットの公式ドキュメント）付きで 確認: 済 として記録しているか、または 確認: 未 として対応する「リスクと対策」の行（再掲した主張で対応付け）を持ち、どう検証/ガードするかを記していることを確認する。残りの主張のうち次に該当するものを `important`（カテゴリ: `feasibility`）として指摘する: スロットに存在しない; 確認: 済 だが根拠が添付されていない; 確認: 済 だがフレームワーク/ライブラリのデフォルトで根拠に解決したパッケージバージョンがない; 確認: 未 だが対応する「リスクと対策」の行がない; または 確認: 未 だが対応する「リスクと対策」の行に下流の `検証先: [ステップまたは成果物]` 伝播（検証戦略または作業計画書のステップへの具体的参照）がない - **既存実装ドキュメント検証**: コード検証結果が提供され、ドキュメントが既存実装を記述している場合（将来の要件ではなく）、コードから観察可能な振る舞いが事実として記述されていることを検証する。確定的な振る舞いに対する推測的な表現 → `important` - **データ設計完全性チェック**: ドキュメントにデータ格納キーワード（database, persistence, storage, migration）またはデータアクセスキーワード（repository, query, ORM, SQL）またはデータスキーマキーワード（table, schema, column）が含まれるにもかかわらず、データ設計コンテンツが不足している場合（スキーマ参照なし、データ層戦略を含む「テスト境界」セクションなし、データモデル文書なし） → `important`（カテゴリ: `completeness`）。注: 「model」「field」「record」「entity」等の汎用語のみでは本チェックを発火しない — データ格納またはデータアクセスキーワードとの共起が必要 - **コード検証連携**: `code_verification`入力が提供された場合、`undocumentedDataOperations`の各項目がドキュメントに不在 → `important`（カテゴリ: `completeness`）。コード検証のseverityが`critical`または`major`の不整合 → 対応するレビューチェックの事前検証エビデンスとして組み込む diff --git a/.claude/agents-ja/technical-designer-frontend.md b/.claude/agents-ja/technical-designer-frontend.md index 5956e5b..e4ab7e2 100644 --- a/.claude/agents-ja/technical-designer-frontend.md +++ b/.claude/agents-ja/technical-designer-frontend.md @@ -14,11 +14,10 @@ skills: documentation-criteria, frontend-technical-spec, frontend-typescript-rul **現在日時の確認**: 作業開始前に`date`コマンドで現在年月日を確認し、最新情報の判断基準とする。 ### 実装への反映 -- documentation-criteriaスキルでドキュメント作成基準を適用 +- 各スキルを担当領域で適用: documentation-criteria、project-context - frontend-technical-specスキルでフロントエンド技術仕様（React、ビルドツール、環境変数）を確認 - frontend-typescript-rulesスキルでフロントエンドTypeScript開発ルール（function components、Props駆動設計）を適用 - coding-standardsスキルで普遍的コーディング規約および実装前の既存コード調査プロセスを適用 -- project-contextスキルでプロジェクトコンテキストを把握 - implementation-approachスキルでメタ認知的戦略選択プロセスを実行（実装アプローチ決定で使用） - typescript-testingスキルでテスト設計基準を適用（テスト可能なAC形式、カバレッジ要件） - llm-friendly-contextスキルで生成物・ハンドオフの明確さ（入力・決定事項・出力構造・成功基準の明示）を確保 @@ -93,7 +92,14 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判 - コードベース外に存在（外部API、別リポジトリ、生成物など） → 公式の出典を記録し「外部依存」としてマーク - どこにも見つからない → Design Docで「新規作成が必要」とマークし、実装順序の依存関係に反映 -5. **Design Docへの記載** +5. **振る舞いに関する主張の検証** + - 設計が依存するが自身では定義しておらず、かつ誤っていれば設計方針が破綻する振る舞い・事実の主張それぞれについて — フレームワーク/ライブラリのデフォルト挙動（「ルーターはデフォルトでスクロール位置を保持する」「フォームライブラリはアンマウント時にリセットする」）、既に提供されていると想定する能力（「フックは既にデバウンスする」「Context は既に Z を公開している」）、既に実装済みと想定する機能（「親で処理済み」）など — 設計時に根拠を1つ添付する: コードベース参照（Grep/Read による file:line）、実行したコマンドの結果、または公式ドキュメント/仕様のURL。フレームワーク/ライブラリのデフォルトについては、デフォルト挙動はバージョンで異なりうるため、公式ドキュメントと（lockfile または設定から）解決したパッケージバージョンをセットで示す。「already」「by default」「defaults to」「handled by」「既に」「デフォルトで」「デフォルトは」「処理済み」「〜で処理する」「自動的に」といった断定的な言い回しは着手の手がかり（網羅ではない）。 + - 根拠がある主張 → Design Doc の「合意事項チェックリスト」の Assumed Behaviors スロットに、根拠とともに 確認: 済 で記録する。 + - 根拠を特定できない主張 → 同じスロットに 確認: 未、根拠: 特定できず で記録し、対応する「リスクと対策」の行を追加する。その行は主張を（共有ルックアップキーとして）再掲し、どう解消するかを記す: 実装時に名前付きの手段（コマンド、テスト、コード確認箇所）で検証する、またはフォールバックでガードする。その解消は下流に `検証先: [ステップまたは成果物]` として伝播し、記録止まりにせず Verification Strategy または作業計画書のタスクにする。 + - スコープと振り分け: ここに記録するのは、設計者が持ち込む振る舞いの前提のうち、他の場所に未記録のものだけ。ある主張が別の記録先にも該当する場合はそちらを優先する — Codebase Analysis が明らかにした構造的な既存事実は Fact Disposition Table へ、前レイヤーの Design Doc から継承した主張は Cross-Layer Assumptions へ。 + - ゲートのタイミング: Assumed Behaviors スロットは Gate 0 の「合意事項チェックリスト」配下にあるが、根拠の収集は上記のコード調査に依存するため、記入はこの Gate 1 で行う。合意事項チェックリストの他項目を最初に埋める時点では空または暫定でよく、この後追いの記入はゲート順序に違反しない。 + +6. **Design Docへの記載** - 「## 既存コードベース分析」セクションに調査結果を必ず記載 - 類似コンポーネントの検索結果（発見したコンポーネント、または「なし」）を明記 - 依存先の存在検証結果（既存確認済み / 新規作成が必要）を記載 @@ -215,19 +221,7 @@ Fact Disposition Table は **構造的な既存事実** を設計に結び付け 各統合ポイントで既存コンポーネントとの競合（命名規則、Propsパターン）を確認し記載する。 ### 変更影響マップ [Gate 3 — Required] -Design Doc作成時に必ず含める： - -```yaml -変更対象: UserProfileCard コンポーネント -直接影響: - - src/components/UserProfileCard/UserProfileCard.tsx (Props変更) - - src/pages/ProfilePage.tsx (使用箇所) -間接影響: - - User context (データ形式変更) - - Theme設定 (スタイルprop追加) -波及なし: - - 他のコンポーネント、APIエンドポイント -``` +Design Doc作成時に必ず含める。3つの層を記録する（YAMLの雛形は design-template.md を参照）: **直接影響**（変更するコンポーネント/ファイルとその使用箇所）、**間接影響**（波及する影響 — データ形式、context/state、スタイルprop）、**波及なし**（明示的に影響を受けない範囲）。 ### インターフェース変更影響分析 [Gate 3 — Required] diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index a48499a..fa690c0 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.claude/agents-ja/technical-designer.md @@ -14,11 +14,8 @@ skills: documentation-criteria, technical-spec, typescript-rules, coding-standar **現在日時の確認**: 作業開始前に`date`コマンドで現在年月日を確認し、最新情報の判断基準とする。 ### 実装への反映 -- documentation-criteriaスキルでドキュメント作成基準を適用 -- technical-specスキルでプロジェクトの技術仕様を確認 -- typescript-rulesスキルでTypeScript開発ルールを適用 +- 各スキルを担当領域で適用: documentation-criteria、technical-spec、typescript-rules、project-context - coding-standardsスキルで普遍的コーディング規約および実装前の既存コード調査プロセスを適用 -- project-contextスキルでプロジェクトコンテキストを把握 - implementation-approachスキルでメタ認知的戦略選択プロセスを実行（実装アプローチ決定で使用） - llm-friendly-contextスキルで生成物・ハンドオフの明確さ（入力・決定事項・出力構造・成功基準の明示）を確保 @@ -93,7 +90,14 @@ ADR/Design Docの作成閾値はdocumentation-criteriaスキルに準拠。判 - コードベース外に存在（外部API、別リポジトリ、生成物など） → 公式の出典を記録し「外部依存」としてマーク - どこにも見つからない → Design Docで「新規作成が必要」とマークし、実装順序の依存関係に反映 -5. **Design Docへの記録** +5. **振る舞いに関する主張の検証** + - 設計が依存するが自身では定義しておらず、かつ誤っていれば設計方針が破綻する振る舞い・事実の主張それぞれについて — フレームワーク/ライブラリのデフォルト挙動（「X のデフォルトは Y」）、既に提供されていると想定する能力（「サービスは既に Z を返す」「エンドポイントは既に W を検証する」）、既に実装済みと想定する機能（「上流で処理済み」）など — 設計時に根拠を1つ添付する: コードベース参照（Grep/Read による file:line）、実行したコマンドの結果、または公式ドキュメント/仕様のURL。フレームワーク/ライブラリのデフォルトについては、デフォルト挙動はバージョンで異なりうるため、公式ドキュメントと（lockfile または設定から）解決したパッケージバージョンをセットで示す。「already」「by default」「defaults to」「handled by」「既に」「デフォルトで」「デフォルトは」「処理済み」「〜で処理する」「自動的に」といった断定的な言い回しは着手の手がかり（網羅ではない）。 + - 根拠がある主張 → Design Doc の「合意事項チェックリスト」の Assumed Behaviors スロットに、根拠とともに 確認: 済 で記録する。 + - 根拠を特定できない主張 → 同じスロットに 確認: 未、根拠: 特定できず で記録し、対応する「リスクと対策」の行を追加する。その行は主張を（共有ルックアップキーとして）再掲し、どう解消するかを記す: 実装時に名前付きの手段（コマンド、テスト、コード確認箇所）で検証する、またはフォールバックでガードする。その解消は下流に `検証先: [ステップまたは成果物]` として伝播し、記録止まりにせず Verification Strategy または作業計画書のタスクにする。 + - スコープと振り分け: ここに記録するのは、設計者が持ち込む振る舞いの前提のうち、他の場所に未記録のものだけ。ある主張が別の記録先にも該当する場合はそちらを優先する — Codebase Analysis が明らかにした構造的な既存事実は Fact Disposition Table へ、前レイヤーの Design Doc から継承した主張は Cross-Layer Assumptions へ。 + - ゲートのタイミング: Assumed Behaviors スロットは Gate 0 の「合意事項チェックリスト」配下にあるが、根拠の収集は上記のコード調査に依存するため、記入はこの Gate 1 で行う。合意事項チェックリストの他項目を最初に埋める時点では空または暫定でよく、この後追いの記入はゲート順序に違反しない。 + +6. **Design Docへの記録** - 「## 既存コードベース分析」: 調査結果、類似機能検索結果（発見した実装または「なし」）、依存先存在検証（既存確認済み / 外部 / 新規作成が必要）、採用した判断（既存使用 / 改善提案 / 新規実装）と根拠。 - 「## コード調査エビデンス」: 調査したすべてのファイルと主要関数。各エントリには関連性タグ（類似機能 / 統合点 / パターン参照）を付ける。 @@ -224,19 +228,7 @@ Fact Disposition Table は **構造的な既存事実** を設計に結び付け 各統合ポイントで既存システムとの競合（優先度、命名規則）を確認し記載する。 ### 変更影響マップ [Gate 3 — Required] -Design Doc作成時に必ず含める: - -```yaml -変更対象: UserService.authenticate() -直接影響: - - src/services/UserService.ts（メソッド変更） - - src/api/auth.ts（呼び出し箇所） -間接影響: - - セッション管理（トークン形式変更） - - ログ出力（新フィールド追加） -波及なし: - - 他のサービス、DB構造 -``` +Design Doc作成時に必ず含める。3つの層を記録する（YAMLの雛形は design-template.md を参照）: **直接影響**（変更するファイル/メソッドとその呼び出し箇所）、**間接影響**（波及する影響 — データ形式、処理時間、ログ出力）、**波及なし**（明示的に影響を受けない範囲）。 ### フィールド伝播マップ [Gate 3 — Required when fields cross component boundaries] 新規または変更されたフィールドがコンポーネント境界を越える場合: diff --git a/.claude/skills-ja/documentation-criteria/references/design-template.md b/.claude/skills-ja/documentation-criteria/references/design-template.md index dc4e8ae..52e532c 100644 --- a/.claude/skills-ja/documentation-criteria/references/design-template.md +++ b/.claude/skills-ja/documentation-criteria/references/design-template.md @@ -52,6 +52,11 @@ unknowns: - [基準/規約] `[explicit]` — 出典: [設定ファイル / ルールファイル / ドキュメントパス] - [観察されたパターン] `[implicit]` — 根拠: [ファイルパス] — 確認: [済/未] +#### Assumed Behaviors +設計が依存するが自身では定義しておらず、かつ誤っていれば設計方針が破綻する振る舞い・事実の主張（フレームワーク/ライブラリのデフォルト、既に提供されていると想定する能力、既に実装済みと想定する機能）のうち、Fact Disposition Table や Cross-Layer Assumptions で既にカバーされていないもの。各主張は根拠とともに 確認: 済 とするか、確認: 未（根拠: 特定できず）として対応する「リスクと対策」の行を持つ — その行は主張を（共有ルックアップキーとして）リスクとして再掲し、どう検証またはガードするかを記し、下流に `検証先: [ステップまたは成果物]` として伝播する。フレームワーク/ライブラリのデフォルトについては、公式ドキュメントと（lockfile または設定から）解決したパッケージバージョンをセットで根拠とする。このスロットは根拠が集まる既存コード調査の段階で記入するため、合意事項チェックリストの他項目を最初に埋める時点では空でよい。該当する主張がなければスロットを N/A とする。 + +- [ ] [主張 — 例: 「フレームワーク X のデフォルトは Y」「サービスは既に Z を返す」] — 根拠: [file:line / コマンド出力 / 解決したパッケージバージョンとセットの doc URL、確認: 未 の場合は「特定できず」] — 確認: [済/未] + #### 品質保証メカニズム 変更対象領域で品質がどのように担保されているか。各項目は adopted（実装時に適用）または noted（観察されたが不採用、理由付き）のいずれか。 @@ -112,11 +117,11 @@ unknowns: ### Fact Disposition Table -コードベース分析の`focusAreas`の各エントリに対して1行ずつ記載する。この表は**構造的な既存事実**と設計を結び付ける主たるテーブルである（Verification StrategyのOutput Comparisonは**ランタイムの振る舞い**を別途拘束する）。既存の振る舞いに言及する他セクションは、この表の行を`fact_id`値で参照する。 +コードベース分析の`focusAreas`の各エントリに対して1行ずつ記載する。この表は**構造的な既存事実**を設計に結び付ける。既存の振る舞いに言及する他セクションは、この表の行を`fact_id`値で参照する。 | Fact ID | Focus Area | Disposition | Rationale | Evidence | Related Files | |---------|------------|-------------|-----------|----------|---------------| -| [focusAreasのfact_id] | [focusAreasのarea] | preserve / transform / remove / out-of-scope | [preserve: 確認のみの文言、例「既存の振る舞いを変更なしで維持」 — 振る舞い変更を主張するRationaleはレビューでpreserve mismatchとして検出される、transform: 新しい観測可能な結果を記述、例「分岐Xは410でなく404を返す」 — 全体として無変更を主張するRationaleはtransform mismatchとして検出される、remove: 理由を記述、ポリシー由来ならPRD/UI Specセクションを引用 — 本番コードパスでの保持を主張するRationaleはremove mismatchとして検出される（テスト/移行スクリプトでの保持を明示した場合は妥当）、out-of-scope: スコープ定義セクションを引用、既存の振る舞いがそのまま残るならpreserveを優先] | [focusAreasのevidence値をそのまま引き継ぎ] | [focusAreas.relatedFilesのパス一覧をそのまま引き継ぎ、カンマ区切り、例: `src/auth/createUser.ts, src/api/routes/users.ts`] | +| [focusAreasのfact_id] | [focusAreasのarea] | preserve / transform / remove / out-of-scope | [disposition別 — preserve: 確認のみの文言（「変更なしで維持」）、transform: 新しい観測可能な結果（「410でなく404を返す」）、remove: 理由 + ポリシー由来ならPRD/UI Specを引用、out-of-scope: スコープ定義セクションを引用] | [focusAreasのevidence値をそのまま引き継ぎ] | [focusAreas.relatedFilesのパス一覧をそのまま引き継ぎ、カンマ区切り、例: `src/auth/createUser.ts, src/api/routes/users.ts`] | ### Cross-Layer Assumptions（レイヤー横断フロー時のみ） @@ -255,7 +260,7 @@ unknowns: ### フィールド伝播マップ（フィールドが境界を越える場合） -ここでの境界には**シリアライズ境界** — 一方の側でエンコードされ、クエリ文字列、CLI引数、環境変数、設定エントリ、メッセージ/キューのペイロード、ストレージキー、ファイルなどの媒体を介して他方の側でパースされる値 — も含まれ、インメモリの受け渡しに限らない。シリアライズ境界の行では `Serialized: [producerが出力する正確な表現]; Parse: [consumerがどうデコード/検証するか]` — すなわち **Serialized Format** と **Consumer Parse Rule** — を付記し、producerとconsumerが合意するようにする。インメモリの受け渡しでは付記を省略する。 +ここでの境界には**シリアライズ境界** — 一方の側でエンコードされ、クエリ文字列、CLI引数、環境変数、設定エントリ、メッセージ/キューのペイロード、ストレージキー、ファイルなどを介して他方の側でパースされる値 — も含まれ、インメモリの受け渡しに限らない。シリアライズ境界の行では **Serialized Format**（`Serialized: [producerが出力する正確な表現]`）と **Consumer Parse Rule**（`Parse: [consumerがどうデコード/検証するか]`）を付記し、producerとconsumerが合意するようにする。インメモリの受け渡しでは付記を省略する。 - [フィールド名]: [コンポーネントA → B] — preserved / transformed / dropped — [理由] - [フィールド名]: [コンポーネントA → B] — transformed — Serialized: [正確な表現]; Parse: [デコード/検証ルール] — [理由]（シリアライズ境界） From 2401ce19b2431f798831824ac90c75006697d475 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Tue, 7 Jul 2026 06:59:25 +0900 Subject: [PATCH 3/3] chore: release 1.25.2 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 6 ++++++ package.json | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34ea885..688ef9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.25.2] - 2026-07-07 + +### Added + +- **Behavioral claim verification** (agents, skills) — Design Docs now back the behavioral/factual claims they rely on but do not themselves define — framework/library defaults, capabilities assumed already provided, features assumed already implemented — with evidence at design time, or bind them to a follow-up. `technical-designer` / `-frontend` gain a Behavioral Claim Verification step (Gate 1) that records each material claim in a new Agreement Checklist "Assumed Behaviors" slot: evidence + `Confirmed: Yes`, or `Confirmed: No` with a matching Risks and Mitigation row propagated downstream as `verify at [step or artifact]`; a framework/library default requires the official doc paired with the resolved package version. Routing defers to the Fact Disposition Table (Codebase Analysis facts) and Cross-Layer Assumptions (prior-layer claims). `document-reviewer` gains a matching evidence check (`important` / `feasibility`). Incidentally trimmed redundant skill cues, the Change Impact example, and duplicated Fact Disposition prose. Applied across en/ja. + ## [1.25.1] - 2026-06-29 ### Added diff --git a/package.json b/package.json index 5163202..72b884f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "create-ai-project", - "version": "1.25.1", + "version": "1.25.2", "packageManager": "npm@10.8.2", "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.", "keywords": [