docs: CLAUDE.md に typecheck 両 tsconfig 明示と deferred promise pattern の注意を追加

[ymnao]

概要

session 126 の PR #392 CI で踏んだ 2 件の落とし穴 (HANDOFF §「CLAUDE.md / HANDOFF への昇格候補」) を CLAUDE.md に恒久事項として昇格。

関連 Issue

なし (HANDOFF §CLAUDE.md 昇格候補起点)

移行 Stage

• Stage 0: 雛形 + フロント表示確認
• Stage 1: ファイル I/O
• Stage 2: ワークスペース・ファイルツリー・ファイル監視
• Stage 3: 全文検索（ripgrep sidecar）
• Stage 4: Git Sync
• Stage 5: OGP / PDF / アップデート
• Stage 6: 仕上げ・配布・切り替え

(該当なし — agent guidelines のみの変更)

変更内容

• 「開発コマンド」節の pnpm typecheck に、素の tsc --noEmit が solution-style 分割 tsconfig を辿らず「0 ファイルチェックで exit 0 (沈黙の成功)」になる挙動と、直叩き時は -p tsconfig.node.json + -p tsconfig.web.json の両方明示、pnpm typecheck script が scripts/generate-katex-css.js を先に走らせる点、CI で pnpm typecheck:e2e も走る点を明記。pnpm typecheck:e2e の実行行も併記
• 「テスト」節に「deferred promise pattern は let x!: T を使う」を追加。TypeScript の CFA (TS 5.x / TS 7 いずれも同挙動、TS 7 固有ではない) が nested function 内の再代入を後続 narrowing に反映せず never 型で TS2349 になる件と、definite assignment assertion で「未代入チェックを免除する」ことで解決する定石を明文化

動作確認

• docs-only 変更につきコード実行なし
• 追記内容の技術的正確性は Fable レビュー (下記エビデンス) で実測裏付け済み
  • tsconfig.node.json / tsconfig.web.json / tsconfig.e2e.json の実在確認
  • package.json:scripts.typecheck が両 tsconfig を叩く実装であることを確認
  • 素の ./node_modules/.bin/tsc --noEmit が「exit 0 / 0 ファイル」の沈黙成功になることを実測
  • null 初期化 + resolveDeferred?.() パターンが TS 7.0.2 / TS 5.9.3 いずれも TS2349 を返し、let x!: () => void パターンで解決することを実測
  • .github/workflows/ci.yml:45-47 で pnpm typecheck と pnpm typecheck:e2e の両方が走ることを確認

スクリーンショット

なし (docs-only)

検証エビデンス

リスク分類

tier: high — agent-config: CLAUDE.md (agent の動作規範を書き換える変更)

実行した検証

種別	コマンド	結果
テスト	(未実施)	docs-only のため未実施
Lint	(未実施)	docs-only のため未実施
Typecheck	(未実施)	docs-only のため未実施
レビュー	Fable code-reviewer (codex-review 3 観点フォールバック、single agent で shell-senior / security / qa-fixture 相当を統合)	0 Critical / 2 Warning / 5 Suggestion — Warning 2 件 + Suggestion 3 件を (a) fix 適用済 (3d73b10)、Suggestion 2 件を (c) 対応しない

レビュー指摘と対応

codex-review は session 122-126 で 5 セッション連続 401 恒常化のため、最初から Fable general-purpose 代替に直行 (session 126 と同じ運用)。

#	Finding	verdict	対応
W1	CLAUDE.md:54 — 「CI 相当」不正確 (pnpm typecheck:e2e も CI で走るが未言及)	CONFIRMED	(a) fix (3d73b10)
W2	CLAUDE.md:228 — TS 7 帰属誤り (TS 5.x でも同挙動の長年仕様)	CONFIRMED	(a) fix (3d73b10)
S1	CLAUDE.md:54 — 直叩き例が pnpm typecheck と等価でない (node scripts/generate-katex-css.js 欠落)	CONFIRMED	(a) fix (3d73b10)
S2	CLAUDE.md:54 — 「project を発見できず」より「0 ファイル沈黙の成功」の方が正確	CONFIRMED	(a) fix (3d73b10)
S3	CLAUDE.md:228 — assertion は「型に伝える」ではなく「免除する」	CONFIRMED	(a) fix (3d73b10)
S4	CLAUDE.md:228 — 配置を「コーディング規約 > TypeScript」節に移すべきか	CONFIRMED (subjective)	(c) 対応しない
S5	(diff 外) scratchpad/ が .gitignore 未登録	CONFIRMED (out-of-scope)	(c) 対応しない

追跡先

Finding (file:line — summary)	行き先	URL / 記録
CLAUDE.md:228 — deferred pattern の配置節	(c) 対応しない	追跡しない (user 指示: 主観的、test helper 文脈限定と割り切れば現位置成立の nit として dismiss を承認)
scratchpad/ — .gitignore 未登録 (diff 外)	(c) 対応しない	追跡しない (user 指示: 本 PR 主旨外、HANDOFF §恒久事項に既記載として dismiss を承認)

Draft 判定

• 判定: normal
• 根拠: step 4 dismiss — 未対応 (a) fix なし・(b) 起票対象なし・(c) 対応しない finding が 2 件あるが 上記追跡先表に user 承認済みで記録済