logic-spike

Vendored from mattpocock/skills · MIT © 2026 Matt Pocock · upstream 6eeb81b · 已汉化并完成 VoidTech 插件内自包含适配。LICENSE 见 ../_vendor-licenses/mattpocock-LICENSE

逻辑 Spike

构建一个小型交互式终端应用，让用户亲自操作状态模型。当问题涉及业务逻辑、状态转换或数据结构，且仅靠文档难以验证时使用。

适用场景

• "我不确定这个状态机能否处理先 X 再 Y 的边界情况。"
• "这个数据模型真的能让我表达……的情况吗？"
• "我想在正式实现前确认这个 API 应该是什么样。"
• 任何用户想要按按钮并观察状态变化的场景。

流程

1. 陈述问题

写代码前，先用一段话说明要验证哪个状态模型、回答什么问题。把这段说明放在原型 README 或文件顶部，便于用户稍后核对。

2. 选择语言

用宿主项目所用的语言。如果项目没有明显的运行时（例如一个文档仓库），就询问。

在工具链上沿用项目现有的约定——不要仅仅为了原型就引入一个新的 package manager 或运行时。

3. 把逻辑隔离进一个可移植的模块

把真正用于回答问题的逻辑放在一个小型、无副作用的接口后面，确保日后可以整体移入正式代码。外层终端界面（TUI）是一次性的，逻辑模块则应保持可复用。

合适的形态取决于问题：

• 一个纯 reducer —— (state, action) => state。当动作是离散事件、状态是单一值时合适。
• 一个状态机 —— 显式的状态与转换。当"此刻到底哪些动作是合法的"本身就是问题的一部分时合适。
• 一小组纯函数，作用于一个朴素数据类型之上。当没有隐含的当前状态、只有变换时合适。
• 一个有清晰方法接口的 class 或模块，当逻辑确实拥有持续的内部状态时。

选择最适合当前问题的结构，而不是最容易接入 TUI 的结构。逻辑模块不做 I/O、不包含终端代码，也不依赖 console.log 控制流程。TUI 可以导入并调用逻辑模块，逻辑模块不能依赖 TUI。

问题得到验证后，可以把 reducer、状态机或函数集移入正式模块，并删除一次性的 TUI。

4. 构建能暴露状态的最小 TUI

构建一个轻量 TUI。每次状态更新后清屏（console.clear()、print("\033[2J\033[H") 或等价方法）并重新渲染完整界面。界面应保持稳定，不要持续追加输出。

每一帧有两部分，按此顺序：

1. 当前状态，使用便于比较的格式输出，例如每行一个字段或格式化 JSON。字段名和区块标题使用加粗，次要信息（时间戳、ID、派生值）使用低亮度。原生 ANSI 转义码即可：\x1b[1m 加粗、\x1b[2m 降低亮度、\x1b[0m 重置。除非项目已有依赖，否则不引入样式库。
2. 键盘快捷键，列在底部：[a] add user [d] delete user [t] tick clock [q] quit。把按键加粗、描述暗淡，或反之——怎么读着清爽就怎么来。

行为：

1. 初始化状态 —— 一个单一的内存对象/结构体。启动时渲染第一帧。
2. 每次读取一个按键（或一行），交给对应的状态处理函数。
3. 每次动作后重渲染整帧——别追加，要替换。
4. 循环直到退出。

整帧应当能放进一屏。

5. 让它一条命令就能运行

在项目现有的 task runner（package.json scripts、Makefile、justfile、pyproject.toml）里加一个脚本。用户应当能运行 pnpm run <prototype-name> 或等价命令——绝不需要记住某个路径。

如果宿主项目没有 task runner，就把命令放在原型 README 的顶部。

6. 交接

把运行命令交给用户，让他们亲自操作。用户发现“不应该出现这个状态”或“结果与预期不同”时，记录对应的模型问题。必要时增加新动作并继续验证。

7. 记录答案

验证完成后，只保留问题结论和可复用逻辑。如果用户在场，确认他们得到的结论；如果用户不在，在原型旁创建 NOTES.md 记录待确认结论，然后再删除原型。

反模式

• **不要加测试。**一个需要测试的原型就不再是原型了。
• **不要接到真实数据库。**用内存存储，除非问题专门就是关于持久化。
• 不要提前支持未来需求。 原型只回答当前问题。
• 不要混合逻辑和 TUI。 如果 reducer 或状态机引用了 console.log、prompt 或终端转义码，它就无法独立复用。TUI 只负责输入和显示，逻辑保留在独立模块中。
• **不要把 TUI 外壳发到生产环境。**外壳是为从终端手动驱动而优化的。它背后的逻辑模块才是值得保留的部分。