夜雨聆风一个项目从需求到交付的三层协同
本章目标
用一个真实案例，完整演示三层协同：
OpenSpec → 定义需求Superpowers → 按流程执行Harness → 全程约束结果：可控、可预测、高质量的代码交付案例：构建一个掘金热榜 CLI 工具
项目背景
我们要开发一个 CLI 工具，抓取掘金 AI 类热榜文章，支持自定义分类和数量。
项目特性
周期：小型项目（实际完成：1 小时） 需求复杂度：低-中 团队规模：1 人 + AI 代理
判断：需要铁三角全套。
第零步：项目初始化（搭建 Harness）
1. 创建项目结构
mkdir hot-trends &&cd hot-trendsnpm init -y2. 搭建 Harness 基础约束
创建 CLAUDE.md：
# hot-trends 项目约定## 项目概述掘金前端热榜 CLI 抓取工具。## 技术栈- 语言：TypeScript (strict mode)- 运行时：Node.js 18+- CLI 框架：commander- 测试：Vitest- 代码风格：ESLint + Prettier## 目录结构src/├── cli/ # CLI 入口├── fetchers/ # 数据抓取（掘金 API）├── filters/ # 过滤逻辑（标签/关键词）├── output/ # 输出格式（表格/JSON）└── utils/ # 工具函数## 代码规范- 变量/函数命名：camelCase- 类型/接口：PascalCase- 文件命名：kebab-case- 所有公开函数必须有 JSDoc## 架构约束- fetcher 只负责抓取，不负责过滤- filter 只负责过滤，不负责存储- 每个模块必须有对应的测试文件- 所有网络请求必须设超时（5秒）## 质量要求- 测试覆盖率 > 80%- 无 ESLint 错误- 所有公开 API 有类型定义## 避免事项- 不要引入重型依赖（优先 Node.js 原生 API）- 不要硬编码 API 地址和超时时间- 不要在 fetcher 中混入过滤逻辑3. 配置 Pre-commit Hook
npminstall-D huskynpx husky init创建 .husky/pre-commit：
#!/usr/bin/env shnpm run lintnpmtest4. 创建基础测试
// tests/smoke.test.tsimport{ describe, it, expect }from'vitest'describe('Smoke Test',()=>{it('should pass',()=>{expect(true).toBe(true)})})Harness 搭建完成 ✓
第一步：初始化 OpenSpec
1. 安装 OpenSpec
# 需要 Node.js 20.19.0+npminstall-g @fission-ai/openspec@latest2. 初始化项目
openspec init输出：
Created openspec/Created openspec/changes/Created openspec/specs/Created openspec/.openspec/config3. 安装 Superpowers
# 在 Claude Code 中/plugin install superpowers@claude-plugins-official环境准备完成 ✓
第二步：创建第一个变更（OpenSpec + Superpowers）
1. 创建变更提案
你：/opsx:propose fetch-juejin-trendsAI 通过 brainstorming skill 逐步澄清需求：
AI（问题 1）：关于 fetch-juejin-trends 的默认分类，你希望默认抓取哪个分类？ 1. AI 类 - 默认抓取 AI 相关的热门文章 2. 综合热榜 - 默认抓取所有分类的综合热榜 3. 前端 - 默认抓取前端分类你：1 AI 类AI（问题 2）：你希望热榜数据在终端如何展示？ 1. 表格形式 - 排名 | 标题 | 作者 | 点赞 | 阅读 2. 列表形式 - 更简洁的垂直排版 3. JSON 格式 - 方便后续处理你：表格形式AI（问题 3）：你希望这个 CLI 工具的命令如何使用？ 1. 单一命令 - 直接运行 2. 带参数的命令 - 支持自定义分类和数量 3. 子命令模式 - 更扩展的方式你：带参数的命令需求确认：
默认分类：AI 类 输出格式：表格形式 命令方式：带参数的命令（–category, --limit）
3. AI 生成方案建议
AI 提出 3 个架构方案：
方案 A（推荐）：模块化分层架构
src/├── cli/index.ts # CLI 入口├── fetchers/juejin.ts # 掘金 API 抓取├── formatters/table.ts # 表格格式化└── types/index.ts # 类型定义方案 B：扁平化单文件方案 C：带缓存的架构
你：方案 A4. AI 生成规范文档
规范文档保存在 docs/superpowers/specs/ 目录：
proposal.md（实际内容）：
specs/fetch.md（实际内容）：
# Fetch Specification## API Endpoint- URL: https://api.juejin.cn/content_api/v1/article/list- Method: POST- Body: { cursor: "0", limit: 20, sort_type: 300, category_id: "6809637769756246023" }## Response Fields- article_info.article_id: string（文章 ID）- article_info.title: string（标题）- article_info.user_info.user_name: string（作者）- article_info.digg_count: number（点赞数）- article_info.view_count: number（阅读量）## Error Handling- 超时：5 秒 AbortController- HTTP 非 200：抛出明确错误信息- 无效响应：检查 data.list 存在性design.md（实际内容）：
# Technical Design## Architecture模块化分层架构（方案 A）## Data Flow用户命令 → CLI 解析参数 → fetchJuejinTrends() → formatAsTable() → 终端输出
## Components| Component | File | Responsibility ||-----------|------|---------------|| Types | src/types/index.ts | Article, Category, FetchOptions 类型定义 || Fetcher | src/fetchers/juejin.ts | API 调用、数据解析、超时控制 || Formatter | src/formatters/table.ts | 表格渲染、数字格式化 || CLI | src/cli/index.ts | 参数解析、流程编排、错误处理 |## Error Handling- 网络超时：5 秒后抛出 AbortError- HTTP 错误：显示状态码- 参数错误：commander 验证 + 自定义范围检查tasks.md（实际内容）：
# Implementation Tasks## 1. 项目初始化- [x] 1.1 配置 TypeScript (tsconfig.json)- [x] 1.2 更新 package.json 依赖和脚本- [x] 1.3 安装依赖## 2. 类型定义- [x] 2.1 创建 src/types/index.ts## 3. 表格格式化 (TDD)- [x] 3.1 编写测试 tests/formatters/table.test.ts- [x] 3.2 实现 src/formatters/table.ts## 4. 数据抓取 (TDD)- [x] 4.1 编写测试 tests/fetchers/juejin.test.ts- [x] 4.2 实现 src/fetchers/juejin.ts## 5. CLI 入口 (TDD)- [x] 5.1 编写测试 tests/cli/index.test.ts- [x] 5.2 实现 src/cli/index.ts## 6. 测试与构建- [x] 6.1 运行完整测试套件- [x] 6.2 验证覆盖率 > 80%- [x] 6.3 编译 TypeScript## 7. 文档- [x] 7.1 创建 README.md4. 确认规范
你：规范确认无误，开始执行OpenSpec 阶段完成 ✓
第三步：执行实施（Superpowers + Harness）
1. 使用 writing-plans 创建实现计划
AI 使用 writing-plans skill 创建详细计划：
AI：正在使用 writing-plans 技能创建实现计划。 计划包含 7 个任务： - Task 1: 项目初始化 - Task 2: 类型定义 - Task 3: 表格格式化工具 (TDD) - Task 4: 掘金数据抓取 (TDD) - Task 5: CLI 入口 (TDD) - Task 6: 运行完整测试和构建 - Task 7: 更新文档 计划保存到：docs/superpowers/plans/2026-05-07-fetch-juejin-trends-plan.md2. 使用 subagent-driven-development 执行
AI 选择子代理驱动方式，为每个任务分发独立子代理：
AI：使用子代理驱动方式执行实现计划。 Task 1: 项目初始化 ├─ 调度实现器子代理 ├─ 创建 tsconfig.json, package.json ├─ 安装依赖（commander, typescript, vitest, eslint） ├─ 两阶段审查（spec + quality） └─ ✓ 完成（SHA: 230f4fa） Task 2: 类型定义 ├─ 调度实现器子代理 ├─ 创建 src/types/index.ts ├─ 定义 Article, Category, CATEGORY_MAP, FetchOptions ├─ 两阶段审查 └─ ✓ 完成（SHA: d3077f3） Task 3: 表格格式化工具 (TDD) ├─ 调度实现器子代理 ├─ 先写测试 tests/formatters/table.test.ts ├─ 实现 src/formatters/table.ts ├─ 测试通过（3 tests） ├─ 两阶段审查 └─ ✓ 完成（SHA: bda3f61） Task 4: 掘金数据抓取 (TDD) ├─ 调度实现器子代理 ├─ 先写测试 tests/fetchers/juejin.test.ts ├─ 实现 src/fetchers/juejin.ts ├─ 测试通过（4 tests） ├─ 两阶段审查（发现超时测试问题，已修复） └─ ✓ 完成（SHA: bd13287, 3344615） Task 5: CLI 入口 (TDD) ├─ 调度实现器子代理 ├─ 先写测试 tests/cli/index.test.ts ├─ 实现 src/cli/index.ts ├─ 测试通过（5 tests） ├─ 两阶段审查 └─ ✓ 完成（SHA: 3435a42） Task 6: 运行完整测试和构建 ├─ 运行所有测试：13 tests passed ✓ ├─ 检查覆盖率：84.5% > 80% ✓ ├─ 编译 TypeScript：成功 ✓ └─ ✓ 完成 Task 7: 更新文档 ├─ 创建 README.md └─ ✓ 完成（SHA: 3df369a）Harness 约束检查（每个任务自动执行）：
AI：检查 CLAUDE.md 约束... ✓ 文件命名：kebab-case（正确） ✓ 类型命名：PascalCase（正确） ✓ 变量/函数：camelCase（正确） ✓ JSDoc：所有公开函数已添加 ✓ ✓ 超时控制：5 秒（正确）✓ ✓ 无过滤逻辑混入 fetcher ✓ ✓ 测试覆盖率：84.5% > 80% ✓ ✓ ESLint：无错误 ✓ ✓ 约束检查通过Superpowers + Harness 执行完成 ✓
第四步：代码审查（Superpowers review skill）
每个任务都经过两阶段审查：
阶段 1：规范审查（Spec Compliance Review）
AI：审查 Task 4 - 掘金数据抓取 ## 规范符合性检查 ✓ 创建 src/fetchers/juejin.ts ✓ 创建 tests/fetchers/juejin.test.ts ✓ 实现 fetchJuejinTrends 函数 ✓ 使用 Node.js 原生 fetch ✓ 超时 5 秒（使用常量） ✓ API 地址通过常量配置 ✓ 返回标准 Article[] 格式 ✓ 仅负责抓取，不过滤 ✓ TDD 流程 ✓ 所有测试通过 ✅ Spec Compliant阶段 2：代码质量审查（Code Quality Review）
AI：代码质量审查 ## Strengths ✓ 类型安全（JuejinResponse 接口） ✓ 错误处理完善（超时、HTTP、无效响应） ✓ 超时机制正确（AbortController + finally 清理） ✓ 常量使用规范 ✓ 文档完善（JSDoc） ## Issues Found ⚠️ Important: 超时测试逻辑不正确（测试 HTTP 408 而非 AbortError） ⚠️ Important: 缺少 HTTP 错误测试 ⚠️ Important: 缺少无效响应测试 建议：修复测试用例修复后重新审查：
你：修复测试AI：已修复超时测试，添加 HTTP 错误和无效响应测试。 测试通过：4/4 tests ✓ 覆盖率提升 ✓ ✅ Approved代码审查完成 ✓
第五步：验证与归档（OpenSpec）
1. 运行完整测试
npmtest输出：
✓ tests/smoke.test.ts (1) ✓ tests/formatters/table.test.ts (3) ✓ tests/cli/index.test.ts (5) ✓ tests/fetchers/juejin.test.ts (4) Test Files 4 passed (4) Tests 13 passed (13) Start at 22:13:53 Duration 628ms2. 检查测试覆盖率
npm run test:coverage输出：
------------|---------|----------|---------|---------|File | % Stmts | % Branch | % Funcs | % Lines |------------|---------|----------|---------|---------|All files | 84.5 | 83.33 | 92.3 | 84.05 | cli | 50 | 72.72 | 50 | 50 | fetchers | 100 | 92.3 | 100 | 100 | formatters | 100 | 83.33 | 100 | 100 | types | 100 | 100 | 100 | 100 |------------|---------|----------|---------|---------|✅ 覆盖率 84.5% > 80% 要求
3. 编译 TypeScript
npm run build输出：无错误 ✓
4. 补归档 OpenSpec 变更
由于实现过程中文档保存在了 docs/superpowers/ 目录，需要手动创建 OpenSpec 构件并归档：
# 创建 OpenSpec 构件mkdir-p openspec/changes/fetch-juejin-trends/specs# 创建 proposal.md, design.md, specs/fetch.md, tasks.md# （从 docs/superpowers/ 目录复制内容）# 执行归档mkdir-p openspec/changes/archivemv openspec/changes/fetch-juejin-trends openspec/changes/archive/2026-05-07-fetch-juejin-trendsgitadd openspec/changes/git commit -m"chore: archive fetch-juejin-trends change"归档结果：
## Archive Complete**Change:** fetch-juejin-trends**Schema:** spec-driven**Archived to:** openspec/changes/archive/2026-05-07-fetch-juejin-trends/**Specs:** No delta specsAll artifacts complete. All tasks complete.第一个功能完成 ✓
第六步：熵管理（Harness）
实际熵管理检查
# 熵管理日报 2026-05-07## 代码质量- [x] ESLint：无错误- [x] 测试覆盖率：84.5%（> 80%）- [x] TODO 注释：0 个- [x] TypeScript strict mode：通过## 文档同步- [x] CLAUDE.md：已存在（项目初始化时创建）- [x] README.md：已更新使用说明- [x] OpenSpec：已归档（2026-05-07-fetch-juejin-trends）- [x] 设计文档：docs/superpowers/specs/2026-05-07-fetch-juejin-trends-design.md- [x] 实现计划：docs/superpowers/plans/2026-05-07-fetch-juejin-trends-plan.md## Git 提交历史- 10 次提交，所有提交信息清晰- 最近提交：3df369a docs: add README with usage instructions## 已知问题- ⚠️ 掘金 API 可能已变更（返回 "请求路由不存在"）- 建议：通过浏览器抓包确认最新 API 接口## 下一步- 修复掘金 API 接口问题- 考虑第二个变更：支持知乎热榜数据源完整流程图（实际实践）
第零步：搭建Harness├──CLAUDE.md已存在（约束定义）├──Pre-commitHook已配置└──基础测试已创建│▼第一步：初始化OpenSpec├──openspecinit（已完成）└──Superpowers已安装│▼第二步：创建变更提案├──/opsx:proposefetch-juejin-trends├──brainstormingskill（3轮问答澄清需求├──提出3个架构方案，选择方案A├──生成规范文档│├──proposal.md│├──design.md│└──specs/fetch.md└──确认规范│▼第三步：执行实施├──writing-plansskill（创建7个任务）├──subagent-driven-development（子代理驱│├─Task1:项目初始化│├─Task2:类型定义│├─Task3:表格格式化(TDD)│├─Task4:数据抓取(TDD)│├─Task5:CLI入口(TDD)│├─Task6:测试与构建│└─Task7:文档├──每个任务：实现器+两阶段审查└──Harness全程约束（10次提交）│▼第四步：代码审查├──每个任务都有spec+quality审查├──发现测试问题并修复└──所有审查通过│▼第五步：归档变更├──运行测试：13testspassed✓├──覆盖率：84.5%>80%✓├──手动创建OpenSpec构件├──/opsx:archive└──归档到：2026-05-07-fetch-juejin-trend│▼第六步：熵管理├──代码质量检查✓├──文档同步检查✓└──记录状态和已知问题│▼✓功能交付三层协同要点总结（实际实践）
总用时：约 65 分钟（从需求到归档）
关键成果：
10 次 Git 提交 13 个测试用例全部通过 测试覆盖率 84.5% 完整的文档记录 规范的归档流程
下一步
你已经看到了一个完整的三层协同流程——从零搭建一个国内可用的 CLI 工具。
下一篇：信息流转与关键节点 —— 深入分析数据在三层之间如何流动。
扩展阅读
OpenSpec 工作流 Superpowers Skills Harness 最佳实践