Back to Details

spec-explore

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec Explore

Spec Explore

核心原则

Core Principles

  1. 探索在先：在 spec-writer 撰写 plan.md 之前完成，为 spec-writer 和 spec-tester 提供充分背景
  2. 条件性 exp-reflect：仅探索新内容时才调用 exp-reflect，纯检索已有经验时不调用
  3. exploration-report.md 是产出：结构化报告，供 spec-writer 和 spec-tester 参考
  1. Explore First: Complete before spec-writer writes plan.md, providing sufficient background for spec-writer and spec-tester
  2. Conditional exp-reflect: Only invoke exp-reflect when exploring new content; do not invoke when only retrieving existing experience
  3. exploration-report.md is the output: A structured report for reference by spec-writer and spec-tester

exp-reflect 触发条件

exp-reflect Trigger Conditions

情况是否触发 exp-reflect
调用 exp-search 检索已有经验❌ 不触发
探索项目现有代码库✅ 触发（知识记忆）
探索外部代码库（如第三方库）✅ 触发（知识记忆）
阅读外部技术文档✅ 触发（知识记忆）
ScenarioTrigger exp-reflect?
Invoke exp-search to retrieve existing experience❌ Do not trigger
Explore the project's existing codebase✅ Trigger (knowledge memorization)
Explore external codebases (e.g., third-party libraries)✅ Trigger (knowledge memorization)
Read external technical documents✅ Trigger (knowledge memorization)

工作流程

Workflow

步骤 1：接收任务

Step 1: Receive Task

从 TeamLead 的 SendMessage 中获取：
  • 当前任务描述
  • 需要探索的范围（项目代码、外部库、文档等）
  • exploration-report.md 的保存路径
Obtain from TeamLead's SendMessage:
  • Current task description
  • Scope of exploration (project code, external libraries, documents, etc.)
  • Save path for exploration-report.md

步骤 2：检索历史经验

Step 2: Retrieve Historical Experience

bash
/exp-search <关键词>
以任务关键词检索，阅读相关经验，记录可参考的历史解决方案。
bash
/exp-search <keywords>
Retrieve using task keywords, read relevant experience, and record referenceable historical solutions.

步骤 3：探索项目现状

Step 3: Explore Project Status

根据任务需要，探索相关代码：
  • 使用 
    Grep
    查找相关代码模式
  • 使用 
    Read
    阅读关键文件
  • 使用 
    Glob
    了解目录结构
[!tip] 探索完成后触发 exp-reflect 探索项目代码后，将新发现调用 exp-reflect 沉淀为知识记忆。
Explore relevant code as needed for the task:
  • Use 
    Grep
    to find relevant code patterns
  • Use 
    Read
    to read key files
  • Use 
    Glob
    to understand directory structure
[!tip] Trigger exp-reflect after exploration After exploring project code, invoke exp-reflect to deposit new findings as knowledge memories.

步骤 4：探索外部资源（如需要）

Step 4: Explore External Resources (if needed)

探索外部代码库（如 AgentScope、第三方库）或技术文档。
[!tip] 探索完成后触发 exp-reflect 探索外部资源后，调用 exp-reflect 将关键发现沉淀为知识记忆。
Explore external codebases (e.g., AgentScope, third-party libraries) or technical documents.
[!tip] Trigger exp-reflect after exploration After exploring external resources, invoke exp-reflect to deposit key findings as knowledge memories.

步骤 5：产出 exploration-report.md

Step 5: Produce exploration-report.md

在 plan.md 同目录下创建 
exploration-report.md
：
markdown
undefined
Create 
exploration-report.md
in the same directory as plan.md:
markdown
undefined

探索报告

Exploration Report

检索到的历史经验

Retrieved Historical Experience

[exp-search 结果摘要，含经验链接]
[Summary of exp-search results, including experience links]

项目现状分析

Project Status Analysis

[相关代码/模块的理解：当前实现、接口、数据结构]
[Understanding of relevant code/modules: current implementation, interfaces, data structures]

外部知识

External Knowledge

[探索外部库/文档的关键发现]
[Key findings from exploring external libraries/documents]

对 Spec 创建的建议

Recommendations for Spec Creation

[给 spec-writer 和 spec-tester 的参考信息：
  • 建议的实现方向
  • 已知的边界情况和风险
  • 可复用的现有组件]
undefined
[Reference information for spec-writer and spec-tester:
  • Recommended implementation directions
  • Known boundary cases and risks
  • Reusable existing components]
undefined

步骤 6：通知 spec-writer 和 spec-tester

Step 6: Notify spec-writer and spec-tester

python
SendMessage(
    recipient="spec-writer",
    content="exploration-report.md 已完成，请阅读后开始撰写 plan.md。路径：{路径}"
)
SendMessage(
    recipient="spec-tester",
    content="exploration-report.md 已完成，请阅读后与 spec-writer 协作撰写 test-plan.md。路径：{路径}"
)
python
SendMessage(
    recipient="spec-writer",
    content="exploration-report.md has been completed. Please read it before writing plan.md. Path: {path}"
)
SendMessage(
    recipient="spec-tester",
    content="exploration-report.md has been completed. Please read it and collaborate with spec-writer to write test-plan.md. Path: {path}"
)

与其他角色的协作

Collaboration with Other Roles

TeamLead → spec-explorer 开始
spec-explorer → exp-search（检索） + 代码探索 + 外部资源探索
spec-explorer → exploration-report.md
spec-explorer → 通知 spec-writer + spec-tester
TeamLead → spec-explorer starts
spec-explorer → exp-search (retrieval) + code exploration + external resource exploration
spec-explorer → exploration-report.md
spec-explorer → Notify spec-writer + spec-tester

后续动作

Follow-up Actions

完成探索后确认：
  1. exploration-report.md 已在正确路径创建
  2. 探索新内容后已调用 exp-reflect 沉淀知识
  3. 已通知 spec-writer 和 spec-tester
After completing exploration, confirm:
  1. exploration-report.md has been created in the correct path
  2. exp-reflect has been invoked to deposit knowledge after exploring new content
  3. spec-writer and spec-tester have been notified

常见陷阱

Common Pitfalls

  • 调用 exp-search 后误触发 exp-reflect（不应触发）
  • exploration-report.md 内容太简略，spec-writer 缺少背景信息
  • 未通知 spec-tester，导致测试计划与设计方案脱节
  • Mistakenly triggering exp-reflect after invoking exp-search (should not trigger)
  • exploration-report.md content is too brief, leaving spec-writer without sufficient background information
  • Not notifying spec-tester, leading to disconnection between test plan and design scheme