Superpowers Day 3 CLI 计算器项目

mokingone
8 阅读8分钟

Superpowers Day 3 CLI 计算器项目

📅 日期

2026-03-22

🎯 今日目标

Day 3：初次体验（2 小时）

  • 创建一个简单的测试项目（CLI 计算器）
  • 使用 Superpowers 完成第一个功能
  • 观察 AI 的行为模式：
    • 它是否先问问题而不是直接写代码？
    • 是否生成了实施计划？
    • 是否先写测试？

📦 项目：CLI 计算器

技术栈

  • Python 3.x
  • pytest（测试框架）
  • Click（CLI 框架）

功能列表

  • 基础运算：加、减、乘、除
  • 支持小数运算
  • 支持表达式（如 2 + 3 * 4）
  • 错误处理（除零、非法输入）

🎬 执行过程记录

阶段 1：项目初始化

项目目录： D:\aicode\learn-superpowers\day3-cli-calculator

项目结构：

day3-cli-calculator/
├── README.md
├── requirements.txt
├── docs/
│   └── superpowers/
│       ├── specs/2026-03-22-cli-calculator-design.md
│       └── plans/2026-03-22-cli-calculator.md
├── src/
│   ├── __init__.py
│   ├── calculator.py
│   └── cli.py
└── tests/
    ├── __init__.py
    ├── test_calculator.py
    └── test_cli.py

初始化完成时间： 2026-03-22 11:57

阶段 2：Superpowers 交互

使用的 Superpowers 技能流程：

  1. brainstorming - 项目设计和需求澄清
  2. writing-plans - 生成详细实施计划
  3. subagent-driven-development - 执行实施计划

阶段 3：观察 AI 行为

✅ 观察清单
观察是/否备注
AI 是否先问问题？✅ 是3个问题逐个询问：交互方式、表达式复杂度、错误处理
是否生成设计文档？✅ 是生成了完整的设计文档并提交到 git
是否生成实施计划？✅ 是14个任务的详细步骤，包含代码示例
是否先写测试？✅ 是每个任务都遵循 TDD：先写测试，再实现
是否遵循 RED-GREEN-REFACTOR？✅ 是完整的 TDD 流程
是否创建 Git Worktree？❌ 否在主分支直接开发（学习项目）
是否进行代码审查？✅ 是规范审查 + 代码质量审查

阶段 4：功能实现（TDD 循环）

Task 1：基础加法

【TDD - RED】编写的测试：

def test_add_two_numbers():
    """测试基础加法：2 + 3 = 5"""
    result = evaluate("2 + 3")
    assert result == 5.0

【TDD - GREEN】实现的代码：

def evaluate(expression: str) -> float:
    """计算数学表达式并返回结果"""
    return eval(expression)

代码审查结果： 功能正确，但存在安全问题（eval 可执行任意代码）

Task 2：基础减法、乘法、除法

【TDD - RED】编写的测试：

def test_subtract_two_numbers():
    result = evaluate("5 - 3")
    assert result == 2.0

def test_multiply_two_numbers():
    result = evaluate("3 * 4")
    assert result == 12.0

def test_divide_two_numbers():
    result = evaluate("10 / 2")
    assert result == 5.0

【TDD - GREEN】实现的代码： 无需修改（eval 已支持）

代码审查结果： 全部通过 ✅

Task 3-6：运算符优先级、括号、小数、边界情况

所有测试一次性添加并全部通过，eval 函数原生支持这些功能。

Task 7：安全检查 - 非法字符

【TDD - RED】编写的测试：

def test_illegal_characters_letters():
    with pytest.raises(ValueError, match="非法字符"):
        evaluate("2 + a")

【TDD - GREEN】实现的代码：

import re

def evaluate(expression: str) -> float:
    allowed_pattern = r'^[\d+\-*/().\s]+$'
    if not re.match(allowed_pattern, expression):
        raise ValueError("错误：表达式包含非法字符")
    if not expression.strip():
        raise ValueError("错误：表达式不能为空")
    return eval(expression)

代码审查结果： 安全检查正确 ✅

Task 8-9：除零错误、语法错误处理

添加了 try-except 块捕获并转换异常为友好的中文错误消息。

Task 11-12：CLI 实现

使用 Click 框架实现命令行接口，包含错误处理和退出码。

阶段 5：集成测试

测试结果：

  • 单元测试：18/18 PASSED
  • CLI 测试：4/4 PASSED
  • 总计：22/22 PASSED ✨

🔍 核心观察

AI 行为观察

是否先问问题？

观察：

  • ✅ 是，通过 AskUserQuestion 工具逐个询问
  • 问题 1：交互方式（单次命令 vs 交互式 vs 两种模式）
  • 问题 2：表达式复杂度（二元运算 vs 优先级 vs 括号）
  • 问题 3：错误处理（崩溃 vs 友好提示 vs 详细诊断）

感受：

  • 非常专业，问题设计合理
  • 多选形式降低了回答难度
  • 每个问题都有清晰的说明和权衡
  • 这避免了后续的返工和误解
是否生成设计文档？

观察：

  • ✅ 是，生成了完整的设计文档
  • 包含：项目结构、API 设计、错误处理、安全检查、测试策略
  • 文档保存到 docs/superpowers/specs/ 并提交到 git

感受：

  • 设计文档非常详细，可读性强
  • 规范审查流程确保了设计质量
  • 文档是后续实施计划的基础
是否生成实施计划？

观察：

  • ✅ 是，14个任务的详细实施计划
  • 每个任务包含：目标、文件、具体步骤、代码示例、预期结果
  • 包含 TDD 流程：写测试 → 运行（失败）→ 实现 → 运行（通过）→ 提交

感受：

  • 计划颗粒度非常细，每个步骤都是 2-5 分钟可完成的
  • 代码示例完整，不需要"猜测"
  • 遵循 YAGNI 和 TDD 原则
  • 计划审查确保了可执行性
是否先写测试？

观察：

  • ✅ 是，每个任务都严格遵循 TDD
  • 任务步骤明确：Step 1 写测试 → Step 2 验证失败 → Step 3 实现代码

感受：

  • TDD 流程被严格执行
  • 测试用例设计合理，覆盖了正常情况和边界情况
  • 测试先行确保了代码的可测试性

TDD 循环观察

RED 阶段

观察：

  • 每个功能都先写测试
  • 测试会失败（因为功能还没实现或实现不完整）
  • 使用 pytest.raises 测试异常情况

感受：

  • RED 阶段让人有明确的目标
  • 失败的测试是开发的路标
GREEN 阶段

观察：

  • 写最少的代码让测试通过
  • 不过度设计，不添加未要求的功能
  • 测试通过后立即提交

感受：

  • 快速反馈循环很有成就感
  • 小步提交让 Git 历史清晰
REFACTOR 阶段

观察：

  • 简单任务（如添加测试）不需要重构
  • 复杂任务（如错误处理）会在后续任务中优化
  • 代码审查会提出重构建议

感受：

  • 项目规模较小，重构需求不多
  • 代码审查充当了质量把关

📊 Day 3 vs Day 1 vs Day 2 对比

维度Day 1（自动）Day 2（手动）Day 3（初次体验）
控制程度🟢 低🔴 高🟡 中等
观察细节❌ 看不到✅ 每步都看到✅ 大部分看到
学习效果📚 中等📚 优秀📚 优秀
效率⚡⚡ 高⚡ 中等⚡⚡ 高
参与感🟢 弱🔴 强🟡 强
TDD 观察❌ 看不到✅ 完整看到✅ 完整看到
AI 行为观察❌ 看不到N/A✅ 重点观察

💡 核心收获

1. Superpowers 的核心价值

流程化：

  • brainstorming → writing-plans → subagent-driven-development
  • 每个阶段都有明确的输入和输出
  • 质量关卡（设计审查、计划审查、代码审查）

提问的艺术：

  • 不假设用户需求，而是通过多选问题澄清
  • 每个选项都有清晰的权衡说明
  • 逐个提问，避免信息过载

计划的重要性：

  • 详细的计划是快速执行的基础
  • 计划越详细，执行中的歧义越少
  • 计划审查避免了返工

2. TDD 的真实体验

RED-GREEN-REFACTOR 不是教条：

  • RED：明确目标
  • GREEN：快速反馈
  • REFACTOR：持续改进（但不是每次都要）

测试的价值：

  • 测试即文档
  • 测试防止回归
  • 测试让重构更安全

3. 子代理驱动开发的优势

独立上下文：

  • 每个子代理有干净的工作上下文
  • 不会"遗忘"或混淆任务

两阶段审查：

  • 规范审查：确保实现了正确的东西
  • 代码质量审查：确保用正确的方式实现

快速迭代：

  • 任务完成后立即审查
  • 问题立即发现和修复

4. 观察到的改进空间

Git 提交粒度：

  • 子代理将测试和实现放在同一提交
  • 无法从 git 历史验证 RED-GREEN 流程
  • 可能需要更严格的提交规范

安全性教育：

  • eval 的安全问题在代码审查中被强调
  • 但在实际执行中等到 Task 7 才修复
  • 对于生产项目，安全应该前置

📦 项目成果

最终文件结构

day3-cli-calculator/
├── README.md                    # 完整的使用文档
├── requirements.txt             # pytest, click
├── docs/superpowers/
│   ├── specs/2026-03-22-cli-calculator-design.md
│   └── plans/2026-03-22-cli-calculator.md
├── src/
│   ├── __init__.py
│   ├── calculator.py            # 25行，包含安全检查
│   └── cli.py                   # 17行，Click CLI
└── tests/
    ├── __init__.py
    ├── test_calculator.py       # 110行，18个测试
    └── test_cli.py              # 35行，4个测试

实现的功能

  • evaluate(expression) - 表达式求值
  • 支持 +, -, *, /, () 运算符
  • 支持运算符优先级
  • 支持小数运算
  • 安全检查（字符白名单）
  • 友好的错误处理
  • CLI 命令行接口

项目统计

  • 代码行数： ~42 行（不含测试和空行）
  • 测试用例： 22 个（18 单元测试 + 4 CLI 测试）
  • Git 提交： ~15 次
  • 测试覆盖率： 100%
  • 开发时间： 约 1.5 小时（含规划）
  • Bug 数量： 0（测试全部通过）

🎯 Day 3 总结

  • 完成基础功能（加减乘除、括号、小数、错误处理）
  • 观察并记录 AI 行为
  • 完成 TDD 流程
  • 记录学习笔记
  • 对比 Day 1 和 Day 2 的体验

Day 3 的独特体验

与 Day 1（自动）相比：

  • 能够看到 AI 的决策过程
  • 理解为什么选择某个方案
  • 学习到系统化的工作方法

与 Day 2（手动）相比：

  • 更高效的执行（子代理并行工作）
  • 自动化的质量审查
  • 保留了学习的价值

最佳平衡：

  • 自动化加速执行
  • 流程化保证质量
  • 可观察性促进学习

🚀 准备进入 Day 4

明天学习重点：

  • 阅读核心技能源码
    • brainstorming/SKILL.md
    • writing-plans/SKILL.md
    • test-driven-development/SKILL.md
  • 深入理解技能的激活条件和工作流程

记录时间：2026-03-22 状态：Day 3 完成 ✅ 项目状态：CLI 计算器已完成，22 个测试全部通过

avatar
文章
阅读
粉丝