flutter-verification

Flutter 完成前验证

概述

未经过验证就声称工作已完成，这不是效率，而是不诚实。

核心原则： 始终先有证据，再作声明。

违反规则的字面要求，就是违背规则的精神。

铁律

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

如果你没有运行本文中的验证命令，就不能声称验证通过。

注意：这是一项由工作流强制执行的 Agent 纪律约定，而非机械门槛——flutter-craft 只提供 SessionStart hook，因此工具层面不会阻止过早声称工作已完成。只有 Agent 遵守时，这条规则才有效。

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：构建成功	“分析通过了”
“功能已完成”	完成所有验证并检查需求	“测试通过了”
“Bug 已修复”	测试原始症状并验证	“代码改过了”
“Widget 可用”	Widget 测试或手动验证	“代码看起来没问题”

危险信号 - 停止

如果你发现自己在想或说：

• “现在应该能用了”
• “大概能通过”
• “看起来没问题”
• “我有信心”
• “就这一次”
• “分析通过了，所以构建也会成功”
• “代码是对的”
• 任何暗示成功但未运行验证的措辞

停止。运行验证命令。

验证清单

声称完成之前：

### 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] [查看：Built successfully] “构建通过” ❌ “分析通过了”（分析不会检查构建）

**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	0 项 WCAG 违规，健康分 ≥ 60	完成
WARN	1-3 项 WCAG 违规（轻微/中度）	建议改进，不会阻止
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)