一个项目从需求到交付的三层协同

本章目标

用一个真实案例，完整演示三层协同：

OpenSpec → 定义需求
Superpowers → 按流程执行
Harness → 全程约束

结果：可控、可预测、高质量的代码交付

案例：构建一个掘金热榜 CLI 工具

项目背景

我们要开发一个 CLI 工具，抓取掘金 AI 类热榜文章，支持自定义分类和数量。

项目特性

  • 周期：小型项目（实际完成：1 小时）
  • 需求复杂度：低-中
  • 团队规模：1 人 + AI 代理

判断：需要铁三角全套。

第零步：项目初始化（搭建 Harness）

1. 创建项目结构

mkdir hot-trends && cd hot-trends
npm init -y

2. 搭建 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

npm install -D husky
npx husky init

创建 .husky/pre-commit：

#!/usr/bin/env sh
npm run lint
npm test

4. 创建基础测试

// tests/smoke.test.ts
import { describe, it, expect } from 'vitest'

describe('Smoke Test', () => {
  it('should pass', () => {
    expect(true).toBe(true)
  })
})

Harness 搭建完成 ✓

第一步：初始化 OpenSpec

1. 安装 OpenSpec

# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

2. 初始化项目

openspec init

输出：

Created openspec/
Created openspec/changes/
Created openspec/specs/
Created openspec/.openspec/config

3. 安装 Superpowers

# 在 Claude Code 中
/plugin install superpowers@claude-plugins-official

环境准备完成 ✓

第二步：创建第一个变更（OpenSpec + Superpowers）

1. 创建变更提案

你：/opsx:propose fetch-juejin-trends

AI 通过 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：带缓存的架构

你：方案 A

4. 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.md

4. 确认规范

你：规范确认无误，开始执行

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.md

2. 使用 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. 运行完整测试

npm test

输出：

 ✓ 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  628ms

2. 检查测试覆盖率

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/archive
mv openspec/changes/fetch-juejin-trends openspec/changes/archive/2026-05-07-fetch-juejin-trends

git add 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 specs

All 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
│
▼
第六步：熵管理
├──代码质量检查✓
├──文档同步检查✓
└──记录状态和已知问题
│
▼
✓功能交付

三层协同要点总结（实际实践）

阶段 OpenSpec Superpowers Harness 实际用时
第零步 - - 搭建约束 已完成
第一步 初始化 安装 - 5 分钟
第二步 创建规范 brainstorming - 10 分钟
第三步 提供tasks writing-plans + subagent-driven 约束检查 30 分钟
第四步 - 两阶段审查（每个任务） - 10 分钟
第五步 归档 - - 5 分钟
第六步 - - 熵管理 5 分钟

总用时：约 65 分钟（从需求到归档）

关键成果：

  • 10 次 Git 提交
  • 13 个测试用例全部通过
  • 测试覆盖率 84.5%
  • 完整的文档记录
  • 规范的归档流程

下一步

你已经看到了一个完整的三层协同流程——从零搭建一个国内可用的 CLI 工具。

下一篇：信息流转与关键节点 —— 深入分析数据在三层之间如何流动。

扩展阅读

# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

OpenClaw 小龙虾本地版一键部署教程｜零配置开箱即用，内置 400 + 大模型

avatar AtomGit开源社区
cover

飞书/钉钉/企微集成型办公Agent：实现一句话触发报销审批

avatar AtomGit开源社区
cover

Java Web 教学辅助平台系统源码-SpringBoot2+Vue3+MyBatis-Plus+MySQL8.0【含文档】

avatar AtomGit开源社区