第 7 章：功能迭代 — 搜索与分类的实现

你将学到什么

• 在已有代码基础上迭代新功能
• /subagent-driven-development vs /executing-plans 两种执行模式对比
• 迭代开发中的上下文管理

7.1 从 P0 到 P1

前面几章我们实现了 P0 功能（笔记 CRUD + localStorage）。现在进入 P1：搜索和分类。

迭代新功能和从零开始不同：

所以迭代时更依赖测试——已有测试是你的安全网。

7.2 为 P1 功能写计划

跟第 4 章一样，先写计划：

/writing-plans

在 NoteFlow P0 基础上实现 P1 功能：

搜索功能：
- 实时搜索（输入即搜索）
- 按标题和内容搜索
- 搜索结果高亮

分类标签：
- 预设标签：工作、生活、学习
- 点击标签筛选笔记
- 笔记可添加/移除标签

已有代码：
- src/utils/storage.js（localStorage 工具）
- src/hooks/useNotes.js（笔记数据管理）
- src/hooks/useSearch.js（搜索 Hook）
- src/components/（NoteList、NoteEditor、SearchBar）

技术约束：与 P0 保持一致

7.3 两种执行模式对比

superpowers 提供两种执行计划的方式：

flowchart TB
    P[实施计划] --> Q{选哪种模式？}

    Q --> A["/subagent-driven-development
━━━━━━━━━━━━━━━
逐个任务执行
每完成一个做两轮 review
串行，不并行"]
    Q --> B["/executing-plans
━━━━━━━━━━━━━━━
批量执行
设置 checkpoint 定期检查
可并行子任务"]

    A --> A1["适合：任务之间有依赖
需要严格质量把关"]
    B --> B1["适合：任务互相独立
追求速度"]

    style A fill:#dbeafe,stroke:#2563eb
    style B fill:#fef3c7,stroke:#d97706

本次选择

搜索和分类功能互相独立（搜索不依赖分类，分类不依赖搜索），可以用 /executing-plans。但我们选择 /subagent-driven-development——因为这是教程，让你看清每一步。

7.4 实战：迭代搜索功能

启动

/subagent-driven-development docs/superpowers/plans/noteflow-p1.md

搜索功能实现要点

implementer subagent 在已有 useSearch Hook 基础上增加高亮功能：

// src/utils/search.js — 新增高亮函数

export function highlightText(text, query) {
  if (!query.trim()) return text;

  const regex = new RegExp(`(${escapeRegex(query)})`, 'gi');
  const parts = text.split(regex);

  return parts.map((part, index) =>
    part.toLowerCase() === query.toLowerCase()
      ? { type: 'highlight', text: part, key: index }
      : { type: 'text', text: part, key: index }
  );
}

function escapeRegex(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

测试：

test('highlightText 标记匹配文本', () => {
  const result = highlightText('Hello World', 'world');
  expect(result).toEqual([
    { type: 'text', text: 'Hello ', key: 0 },
    { type: 'highlight', text: 'World', key: 1 },
    { type: 'text', text: '', key: 2 },
  ]);
});

test('highlightText 空搜索返回原文', () => {
  const result = highlightText('Hello', '');
  expect(result).toEqual([{ type: 'text', text: 'Hello', key: 0 }]);
});

spec reviewer 发现的问题

❌ Spec 不通过

• 缺失：搜索结果数量显示（spec 要求"显示 X 条结果"）
• 缺失：搜索无结果时的空状态提示

implementer 修复

添加搜索结果计数和空状态：

// src/components/SearchBar.jsx — 增加
<div className="search-info">
  {query && (
    <span className="search-count">
      找到 {filteredNotes.length} 条结果
    </span>
  )}
</div>

// src/components/NoteList.jsx — 增加空状态
{filteredNotes.length === 0 && query && (
  <div className="empty-state">
    <p>没有找到包含 "{query}" 的笔记</p>
    <p className="empty-hint">试试其他关键词？</p>
  </div>
)}

spec reviewer 复查

✅ 通过 — 所有需求均已实现

7.5 实战：迭代分类标签

分类功能的实现独立于搜索。implementer subagent 需要：

1. 扩展数据结构：给笔记添加 tags 字段
2. 创建标签组件：TagSelector.jsx
3. 实现筛选逻辑：useTagFilter.js

关键代码：数据迁移

已有笔记没有 tags 字段，需要迁移：

// src/utils/migration.js

export function migrateNotes(notes) {
  return notes.map(note => ({
    ...note,
    tags: note.tags || [],  // 旧笔记补充空标签数组
  }));
}

测试：

test('旧笔记数据迁移', () => {
  const oldNotes = [
    { id: '1', title: 'Test', content: 'Hi', createdAt: 1, updatedAt: 1 },
  ];
  const migrated = migrateNotes(oldNotes);
  expect(migrated[0].tags).toEqual([]);
});

test('已有标签的笔记不变', () => {
  const notes = [
    { id: '1', title: 'Test', content: 'Hi', tags: ['工作'], createdAt: 1, updatedAt: 1 },
  ];
  const migrated = migrateNotes(notes);
  expect(migrated[0].tags).toEqual(['工作']);
});

7.6 上下文管理：/compact

到了这一步，对话可能已经很长了。Claude Code 的上下文窗口有限，太长的对话会影响性能。

用 /compact 压缩对话：

/compact

它会：

1. 总结之前的对话内容
2. 保留关键信息（代码决策、测试结果）
3. 丢弃冗余内容（重复的审查输出）
4. 释放上下文空间给后续任务

什么时候该 compact：

• 对话超过 20 轮
• Claude 开始"忘记"前面的代码
• 响应变慢或质量下降

7.7 两种模式的实际选择建议

flowchart TB
    Q{任务之间有依赖吗？}
    Q -- "有依赖" --> A["/subagent-driven-development
串行执行，每步 review"]
    Q -- "互相独立" --> R{质量要求高吗？}
    R -- "高（首次实现）" --> A
    R -- "低（重复模式）" --> B["/executing-plans
批量执行，checkpoint 检查"]

    style A fill:#dbeafe,stroke:#2563eb
    style B fill:#fef3c7,stroke:#d97706

动手做

1. 为 P1 功能写一份实施计划
2. 用 /subagent-driven-development 执行搜索功能
3. 观察搜索的 review 循环
4. 继续执行分类功能
5. 运行 /compact 压缩对话
6. 运行全量测试确认没有回归

本章小结

核心原则： 迭代开发时测试比从零开始更重要。每个新功能都应该跑全量测试，确认没有破坏已有功能。