ECC 项目 search-first 技能全解：把“先搜索、后编码“固化为 Agent 的研究驱动工作流-迪斯科星球

ECC 项目 search-first 技能全解：把"先搜索、后编码"固化为 Agent 的研究驱动工作流

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文围绕 ECC 仓库（Everything Claude Code）在.kiro平台侧发布的search-first技能文档（.kiro/skills/search-first/SKILL.md）展开。它以一句口号立骨——Research Before You Code（编码之前先做研究）——把"动手写代码前先检索仓库、包注册表、MCP、技能库与开源社区中是否已有现成方案"这件事，从一句口头禅系统化成一个含触发条件、审批边界、五阶段流程、决策矩阵、模式分级和反模式清单的可执行工作流。读完本文，你将掌握：如何在 Agent 会话里用 Quick Mode 做低成本内联检索、何时用 Full Mode 委派 researcher 子代理做并行调研、如何依据"Adopt / Extend / Compose / Build"矩阵做依赖取舍，以及如何把该技能与 planner、architect 等 Agent 及 iterative-retrieval 技能拼接成"渐进式检索"流水线。

search-first 在 ECC 仓库中的定位

search-first不是某个 CLI 命令，而是一个Skill（技能）——一种通过/菜单或显式引用触发的按需工作流。它的 YAML frontmatter 声明如下：

--- name: search-first description: > Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. Systematizes the "search for existing solutions before implementing" approach. Use when starting new features or adding functionality. metadata: origin: ECC ---

在仓库中，search-first 技能存在两份并行文本：

位置	特点
.kiro/skills/search-first/SKILL.md	Kiro 平台侧的完整版，额外包含Scope and Approval Rules（范围与审批规则），强调"只读研究 + 显式审批"边界（本文主体）
skills/search-first/SKILL.md	仓库主干`skills/`目录下的同源版本，额外补充Step 0: Tool Availability Preflight（搜索通道可用性预检）与`Agent(...)`调用片段，可作为对照扩展阅读

.kiro/是 ECC 的 Kiro 移植载体。其 README 明确写道：该项目把 ECC 的 agents、skills、hooks、steering files 与 scripts 带入 Kiro，可通过.kiro/install.sh一键安装到任意 Kiro 项目。在它的技能清单表中，search-first被描述为："Search-first development methodology. Use when exploring unfamiliar codebases or debugging issues."（搜索优先的开发方法论，用于探索陌生代码库或排查问题时）。

同时，search-first已被登记进 ECC 的技能目录清单（agent.yaml 中skills:一节）与模块安装清单（manifests/install-modules.json 中的skills/search-first条目），说明它是 ECC 官方技能目录的一员，而非孤立的散落文件。

触发条件（Trigger）：什么场景该先停下来搜索

技能文档给出了四条高度实用的触发时机，覆盖从"接到新需求"到"准备写抽象层"的常见动作点：

启动一个很可能已有现成方案的新功能时；
计划新增依赖或做第三方集成时；
用户说"帮我加 X 功能"、而你正要开始写代码的那一刻；
准备新建一个工具函数、helper 或抽象层之前。

这四条触发条件的共性在于：在"创造"之前先检查"是否存在"。技能把这一检查放在代码写入动作的前置位，从而最大化复用收益。

Scope 与审批规则：默认只读，写入需授权

.kiro版技能最重要的纪律条款是Scope and Approval Rules，它把该技能的默认行为边界划得清清楚楚：

默认只读研究：先检查仓库、包元数据、文档与公开示例，再给出依赖/集成建议。
禁止越权操作：未经用户在当前任务中明确批准，不得安装软件包、配置 MCP 服务器、发布产物、开 PR 或发起任何外部写入动作。
审批检查点：当候选方案涉及凭据、付费服务、网络写入或全项目级配置变更时，只返回建议与审批检查点（approval checkpoint），而不是直接落地。

这条规则与本仓库mcp-configs/mcp-servers.json中大量 MCP 服务器需要YOUR_*_HERE占位凭据的设计一脉相承——仓库把"需要密钥/付费/写操作"的能力显式标记为 opt-in，等待人工配置，而非默认启用。

工作流总览：五阶段"搜索优先"主循环

技能把整个流程抽象为下图所示的五阶段管线，从需求澄清一路走到"审批通过后实施"：

┌─────────────────────────────────────────────┐ │ 1. NEED ANALYSIS │ │ Define what functionality is needed │ │ Identify language/framework constraints │ ├─────────────────────────────────────────────┤ │ 2. PARALLEL SEARCH (researcher agent) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ npm / │ │ MCP / │ │ GitHub / │ │ │ │ PyPI │ │ Skills │ │ Web │ │ │ └──────────┘ └──────────┘ └──────────┘ │ ├─────────────────────────────────────────────┤ │ 3. EVALUATE │ │ Score candidates (functionality, maint, │ │ community, docs, license, deps) │ ├─────────────────────────────────────────────┤ │ 4. DECIDE │ │ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ │ │ Adopt │ │ Extend │ │ Build │ │ │ │ as-is │ │ /Wrap │ │ Custom │ │ │ └─────────┘ └──────────┘ └─────────┘ │ ├─────────────────────────────────────────────┤ │ 5. APPROVAL CHECKPOINT / IMPLEMENT │ │ Recommend package / MCP / custom code │ │ Apply only after explicit approval │ └─────────────────────────────────────────────┘

各阶段职责拆解：

NEED ANALYSIS（需求分析）：先把"需要什么能力"写清楚，并识别语言/框架约束。这一步是后续一切检索的关键词来源；
PARALLEL SEARCH（并行检索）：由 researcher 角色在同一时间推进 npm/PyPI、MCP 服务器、GitHub/Web 三条搜索通道，互不阻塞；
EVALUATE（评估）：对候选按功能性、维护活跃度、社区、文档、许可证、依赖体量六维打分；
DECIDE（决策）：把候选归类到 Adopt / Extend / Compose / Build 四象限；
APPROVAL CHECKPOINT / IMPLEMENT（审批检查点/实施）：给出"推荐包 / 推荐 MCP / 推荐自定义代码"的建议，但仅在用户明确批准后才落地安装或配置变更。

值得注意：.kiro版刻意把第 5 步命名为 "Approval Checkpoint / Implement"，与它的 Scope and Approval Rules 完全一致；而同仓库主干版（skills/search-first/SKILL.md）在第 0 步额外加入Tool Availability Preflight，用一张预检表约束检索的真实性，详见下文"模式一"。

决策矩阵：四个动作信号的取舍逻辑

检索结果落进下表四象限，是整个过程最关键的判断工具：

Signal	Action
Exact match, well-maintained, MIT/Apache	Adopt— recommend the package and request approval before install or config changes
Partial match, good foundation	Extend— recommend the package plus a thin wrapper, then wait for approval before applying
Multiple weak matches	Compose— propose 2-3 small packages and the integration plan before installing anything
Nothing suitable found	Build— explain why custom code is warranted, then implement only within the approved task scope

解读这张表的判据设计：

完全匹配 + 维护良好 + MIT/Apache 宽松许可→直接采纳（Adopt）：注意不是立刻装，而是"推荐 + 申请审批后再装"，把许可合规（License）与维护状态（Maintained）视为硬门槛；
部分匹配、底子不错→采纳后包一层薄封装（Extend）：保持第三方实现为内核，只写自定义的薄 wrapper，避免重造轮子；
多个弱匹配→组合（Compose）：在安装任何东西之前先提出 2–3 个小包的组合方案与集成计划，用多个小而专的依赖替代一个臃肿的大依赖；
确实没有合适方案→自定义（Build）：此时必须解释为何值得自研，且只在已批准的任务范围内实施。

这套矩阵的价值在于：把"要不要自己写"从拍脑袋升级为基于信号证据的分支决策，并且无论哪个分支都不绕过审批闸门。

两种使用模式

技能为不同量级的需求提供了两个入口：轻量的内联快查（Quick Mode）与重型的子代理调研（Full Mode）。

Quick Mode（内联快速模式）

在准备写一个工具函数或加功能之前，先在脑内自上而下快速过一遍这五问：

仓库里是否已存在？→ 先检索相关模块与测试；
这是否是常见问题？→ 去 npm/PyPI 检索；
是否有对应 MCP？→ 检查 MCP 配置并检索；
是否已有现成 skill？→ 检查可用技能库；
是否有 GitHub 上的实现/模板？→ 在写全新代码之前，先跑 GitHub 代码搜索找维护良好的开源方案。

这五问是一个从内向外的漏斗：仓库内部 → 包生态 → 协议层（MCP）→ 技能库 → 开源社区，由近及远、成本由低到高。

配套的预检纪律（见主干版 skills/search-first/SKILL.md 的 Step 0）要求：先确认每个通道真的可用，再声称覆盖了该通道——例如用rg --files与定向rg做仓库检索、用npm --version/python -m pip --version确认注册表可访问、用gh auth status确认 GitHub CLI 已登录、用当前工具列表或本地 MCP 配置确认检索工具存在、用ls ~/.claude/skills ~/.codex/skills（如适用）确认技能目录存在。若某通道缺失，则应如实声明"只检查了可见文件"或"无本地技能目录"，不得谎报检索覆盖范围。

Full Mode（子代理调研模式）

对非平凡（non-trivial）的功能需求，技能建议把调研委托给研究型子代理，并给出了可直接套用的提示词骨架：

Invoke subagent with prompt: "Research existing tools for: [DESCRIPTION] Language/framework: [LANG] Constraints: [ANY] Search: npm/PyPI, MCP servers, skills, GitHub Return: Structured comparison with recommendation"

主版本（skills/search-first/SKILL.md）同时给出了面向 Agent API 的等价写法：

Agent(subagent_type="general-purpose", prompt=" Research existing tools for: [DESCRIPTION] Language/framework: [LANG] Constraints: [ANY] Search: npm/PyPI, MCP servers, Claude Code skills, GitHub Return: Structured comparison with recommendation ")

并且提示了一个跨版本的兼容细节：较老的 Claude Code 文档中该能力叫Task(...)，使用时以当前宿主 harness 暴露的 agent/subagent 工具名称为准——这正是 ECC "一套技能适配多种 harness"的典型处理方式。

这种"委派式"调研与仓库中研究向 Agent 的分工一致：例如 agents/code-explorer.md（Code Explorer Agent）就是典型的只读研究型角色，其工具面仅含 Read / Grep / Glob，输出"入口点 → 执行流 → 架构洞察 → 关键文件表 → 依赖清单 → 新开发建议"，是 search-first 全流程中"第 0 步仓库内检索"的可执行化样板。

分类检索快捷键：按需求直接命中候选

技能按四大场景预置了高频检索捷径，显著降低每次搜索的试错成本：

开发工具链（Development Tooling）

Linting →eslint、ruff、textlint、markdownlint
Formatting →prettier、black、gofmt
Testing →jest、pytest、go test
Pre-commit →husky、lint-staged、pre-commit

AI/LLM 集成（AI/LLM Integration）

Claude SDK → 检查最新官方文档
Prompt management → 先查 MCP 服务器
文档处理 →unstructured、pdfplumber、mammoth

数据与 API（Data & APIs）

HTTP 客户端 → Python 用httpx，Node 用ky/got
数据校验 → TS 用zod，Python 用pydantic
数据库 → 先查是否有现成 MCP 服务器

内容与发布（Content & Publishing）

Markdown 处理 →remark、unified、markdown-it
图片优化 →sharp、imagemin

这些"预设通道"与仓库内 mcp-configs/mcp-servers.json 实际登记的一批检索型 MCP 服务器可以一一对上：context7提供"实时文档查询"（对应 Claude SDK 查最新文档）、exa-web-search与parallel-search提供网络检索与信息摄取（对应 GitHub/Web 通道）、memory/omega-memory提供跨会话检索。技能建议保持启用 MCP 数量在 10 个以内以保护上下文窗口——这与检索优先、克制依赖的理念是同一逻辑的两面。

与上游 Agent / 技能的分工集成

search-first不是一个孤岛技能，文档专门定义了它与规划、架构角色的协作契约：

与 planner agent 协作

planner 应在进入 Phase 1（架构评审）之前先调用 researcher：

researcher 先识别出可用的工具与方案；
planner 再把这些方案吸收进实施计划；
从而避免在计划阶段就"重复造轮子"。

与 architect agent 协作

architect 应在以下三类决策时咨询 researcher：

技术栈选型（Technology stack decisions）；
集成模式发现（Integration pattern discovery）；
参考架构调研（Existing reference architectures）。

与 iterative-retrieval 技能结合：渐进式发现

文档明确建议把 search-first 与 skills/iterative-retrieval/SKILL.md 结合成三轮递进检索循环：

Cycle 1（宽检索）：在 npm、PyPI、MCP 上做广撒网式搜索；
Cycle 2（细评估）：对排名靠前的候选做逐项深入评估；
Cycle 3（兼容性验证）：验证候选与项目约束的兼容性。

这正是 iterative-retrieval 技能所描述的"先宽后窄、最多三轮"检索节奏：它把子代理"不知道自己需要什么上下文"的问题拆成 DISPATCH（派发初始宽查询）→ EVALUATE（按 0–1 打分相关性）→ REFINE（用学到的术语与排除路径改写查询）→ LOOP（最多 3 轮后收敛）四个阶段。search-first 负责"找现成方案"，iterative-retrieval 负责"找到后把上下文逐步喂给子代理"，二者组合覆盖了"调研 → 实施"的完整上下文供给链路。

三个可复制的实战案例

技能文档用三个案例完整演示了从需求到动作的全过程，注意每一条的落点都以"先询问、后安装"收尾：

案例一："加一个死链检查功能"

Need: Check markdown files for broken links Search: npm "markdown dead link checker" Found: textlint-rule-no-dead-link (score: 9/10) Action: ADOPT — recommend `textlint-rule-no-dead-link` and ask before installing it Result: Zero custom code if approved, battle-tested solution

案例二："加一个 HTTP 客户端封装"

Need: Resilient HTTP client with retries and timeout handling Search: npm "http client retry", PyPI "httpx retry" Found: got (Node) with retry plugin, httpx (Python) with built-in retry Action: ADOPT — recommend `got`/`httpx` directly with retry config and ask before changing dependencies Result: Zero custom code if approved, production-proven libraries

案例三："加一个配置文件 linter"

Need: Validate project config files against a schema Search: npm "config linter schema", "json schema validator cli" Found: ajv-cli (score: 8/10) Action: ADOPT + EXTEND — recommend `ajv-cli` plus a project-specific schema, then wait for approval before install/write Result: 1 package + 1 schema file if approved, no custom validation logic

三个案例共同勾勒出该技能的典型"成功形态"：授权后零（或接近零）自定义代码 + 经过实战检验的既有方案。案例三尤其说明 Extend 分支——ajv-cli之外只需补一个项目专属 schema 文件，验证逻辑本身不需要手写。

反模式清单：搜索优先最该避开的四个坑

技能最后用四个反模式标出了工作流最常失守的节点：

Jumping to code（跳过搜索直接写码）：不先确认是否有现成工具就动手写 utility——这是 search-first 的首要打击对象；
Ignoring MCP（无视 MCP）：没有检查某个 MCP 服务器是否已经提供了该能力，导致重复实现；
Over-customizing（过度自定义）：把第三方库包了一层又一层，包到它失去了自身价值；
Dependency bloat（依赖臃肿）：为了一个小功能装进一个庞大的包——这与决策矩阵中 Compose"用 2–3 个小包"的取向正好相反。

主干版技能在 skills/search-first/SKILL.md 中另补充了一条更隐蔽的反模式：Silent skipping（静默跳过）——当某个搜索通道不可用时却报告"什么都没找到"。这正是 Step 0 预检要堵住的漏洞：诚实报告通道缺失，远胜于给出虚假的"零结果"结论。

小结：把"搜索优先"变成可审计的工程纪律

纵观 .kiro/skills/search-first/SKILL.md 全文，search-first 的核心贡献可以归纳为三点：

把常识流程化：从"动手前应该搜一搜"的松散直觉，收敛为"需求分析 → 并行检索 → 六维评估 → 四象限决策 → 审批后实施"的固定管线，每一步都有明确产出；
把边界纪律化：默认只读、写入必须审批、凭据/付费/全项目配置变更一律先出 approval checkpoint，让"研究"与"执行"在权限上物理隔离；
把复用通道化：内联快查五连问 + 分类检索快捷键 + researcher 子代理委派 + planner/architect/iterative-retrieval 协同，构成一套自内向外、层层递进的检索体系。

对任何一个正在构建 Agent 工作流的团队而言，search-first 提供了一份可直接采纳的"去重复发明"模板：它的决策矩阵与反模式清单可以在任何 Agent harness（Claude Code、Codex、Kiro 乃至自定义编排层）中复用，而 ECC 仓库中的主干版技能、技能目录声明、安装模块清单与平台移植说明则共同保证了这个技能在仓库内的可发现、可安装与可维护。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析