flutter-verification

完了前の Flutter 検証

概要

検証せずに作業が完了したと主張するのは、効率ではなく不誠実です。

基本原則：常に、主張より先に証拠を示します。

このルールの文言に違反することは、このルールの精神に違反することです。

鉄則

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

このメッセージに記載された検証コマンドを実行していない場合、合格したと主張することはできません。

注：これはワークフローによって徹底されるエージェントの規律に関する慣習であり、機械的なゲートではありません。flutter-craft が提供するのは SessionStart フックのみであるため、ツールレベルで早まった完了報告がブロックされることはありません。このルールが守られるのは、エージェントが従う限りにおいてです。

Flutter の検証コマンド

1. 静的解析（常に必須）

flutter analyze

期待される出力：

Analyzing <project>...
No issues found!

問題が見つかった場合：

Analyzing <project>...
   info • ... • lib/path/file.dart:42:10 • ...
   warning • ... • lib/path/file.dart:50:5 • ...

3 issues found. (1 warning, 2 hints)

2. 単体テスト（優先度 1 および 2）

# All tests
flutter test

# Specific feature tests
flutter test test/features/<feature>/

# Specific test file
flutter test test/features/<feature>/data/repositories/user_repository_test.dart

期待される出力：

00:05 +12: All tests passed!

テストが失敗した場合：

00:03 +10 -2: Some tests failed.

3. ビルド検証（完了段階で一度実行 — 完了を主張するたびに実行するものではありません）

プロジェクトで実際に対象としているプラットフォームに対してのみ実行します。

# Android
flutter build apk --debug

# iOS (macOS only)
flutter build ios --debug --no-codesign

# Web
flutter build web

# Desktop
flutter build windows / macos / linux

期待される出力（例：Android）：

✓ Built build/app/outputs/flutter-apk/app-debug.apk (XX.XMB)

4. フォーマットチェック（任意）

dart format --set-exit-if-changed lib/

ゲート機能

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Flutter でよくある失敗

主張	必要な条件	不十分な条件
「コードに問題はありません」	flutter analyze：問題なし	「正しいコードを書きました」
「テストに合格しました」	flutter test：すべて合格	「合格するはずです」「正しそうです」
「ビルドに成功しました」	flutter build：ビルド成功	「解析に合格しました」
「機能が完成しました」	すべての検証 ＋ 要件の確認	「テストに合格しました」
「バグを修正しました」	元の症状をテストして検証	「コードを変更しました」
「ウィジェットは動作します」	ウィジェットテストまたは手動検証	「コードは正しそうです」

危険信号 — STOP

次のように考えたり、言ったりしていることに気づいたら：

• 「これで動くはずです」
• 「おそらく合格します」
• 「正しそうです」
• 「自信があります」
• 「今回だけです」
• 「解析に合格したので、ビルドも成功するはずです」
• 「コードは正しいです」
• 検証を実行せずに成功を示唆する表現はすべて

STOP。検証コマンドを実行してください。

検証チェックリスト

完了を主張する前に：

### Verification Results

**Static Analysis:**
```bash
$ flutter analyze
Analyzing flutter_app...
No issues found!

✅ 合格

単体テスト：

$ flutter test test/features/<feature>/
00:05 +12: All tests passed!

✅ 12/12 合格

ビルド：

$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk

✅ ビルドに成功しました

完了を主張する準備ができました。

## Key Patterns

**Static Analysis:**

✅ [flutter analyze を実行] [「No issues found!」を確認] 「解析に合格しました」 ❌ 「コードに問題はなさそうです」／「正しく書きました」

**Tests:**

✅ [flutter test を実行] [34/34 合格を確認] 「すべてのテストに合格しました」 ❌ 「今度は合格するはずです」／「テストは正しそうです」

**Build:**

✅ [flutter build を実行] [ビルド成功を確認] 「ビルドに合格しました」 ❌ 「解析に合格しました」（解析ではビルドを確認しません）

**Feature completion:**

✅ 計画を再確認 → 各要件を検証 → すべての検証を実行 → 報告 ❌ 「テストに合格したので、機能は完成しました」

## Rationalization Prevention

| Excuse | Reality |
|--------|---------|
| "Should work now" | RUN flutter analyze/test |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Analyze passed" | Analyze ≠ build ≠ test |
| "Code looks right" | Verify independently |
| "I'm tired" | Exhaustion ≠ excuse |
| "It's simple code" | Simple code can still fail |

## Why This Matters

- **Trust:** If you claim "tests pass" without running them, trust is broken
- **Time:** False completion → redirect → rework wastes everyone's time
- **Quality:** Unverified code may crash in production
- **Integrity:** Honesty is a core value

## When To Apply

**ALWAYS before:**
- ANY variation of success/completion claims
- ANY expression of satisfaction ("Done!", "Fixed!", "Works!")
- Committing code
- Creating PRs
- Moving to next task
- Reporting to user

## The Bottom Line

**No shortcuts for verification.**

Run the command. Read the output. THEN claim the result.

```bash
# Always run these before claiming completion:
flutter analyze
flutter test

これは譲れないルールです。

完了を主張するたびに flutter build を実行する必要はありません。時間がかかり、プラットフォームにも依存するためです。flutter-finishing で一度だけ、プロジェクトで実際に対象としているプラットフォームに対して実行します。

---

5. 視覚的な検証（任意 — Flutter Web）

UI の変更を含む作業では、design-polish プラグインがインストールされている場合、視覚的な検証を実施します。 インストールされていない場合は、この手順をスキップしてください（SOFT_FAIL）。

前提条件

• design-polish プラグインがインストールされている（~/.claude/plugins/marketplaces/design-polish または ~/.claude/plugins/design-polish）
• scripts/capture.cjs が存在する
• Node.js と npx が利用可能

手順

1. Flutter Web をビルドする

   flutter build web
   

2. ビルド出力をローカルで配信する

   npx serve build/web -l 3000 &
   SERVER_PID=$!
   

3. スクリーンショットを撮影し、WCAG チェックを実行する

   BASE_URL=http://localhost:3000 node <design-polish-path>/scripts/capture.cjs --wcag /
   

4. 結果を確認する

   • .design-polish/health-score.json：デザインの健全性スコア（0～100）
   • .design-polish/accessibility/wcag-report.json：WCAG 違反
   • .design-polish/screenshots/current-main.png：現在のスクリーンショット

5. サーバーを停止する

   kill $SERVER_PID 2>/dev/null
   

判定基準

結果	条件	アクション
PASS	WCAG 違反が 0 件、ヘルススコア ≥ 60	完了
WARN	WCAG 違反が 1～3 件（軽度／中程度）	改善を推奨します。ブロックはしません
FAIL	重大な WCAG 違反が存在する	修正を推奨します（SOFT_FAIL：ブロックしません）
SKIP	design-polish がインストールされていない	スキップ

証跡記録

**Visual Verification:**
- Health Score: 85/100
- WCAG: 0 violations
- Screenshot: .design-polish/screenshots/current-main.png
✅ Visual check passed (or ⚠️ skipped / ⚠️ warnings found)