arch-search

name	arch-search
description	通过搜索架构文档替代直接搜索项目代码，平均节省 70% Token 消耗。 使用场景：定位功能实现位置、了解模块设计、回答架构问题。
argument-hint	[search-term]
disable-model-invocation	false
user-invocable	true
context	fork
agent	Explore
allowed-tools	Read, Grep, Glob

架构搜索

快速开始

显式触发

用户: "搜索认证功能在哪里实现的"
用户: "查找数据库设计文档"
用户: "API 端点定义在哪"

隐式触发

当 AI 执行开发任务时自动触发：

• 收到 "实现 XXX 功能" → 自动搜索定位代码
• 收到 "修复 XXX 问题" → 自动搜索相关模块
• 回答 "XXX 是怎么实现的" → 自动搜索架构文档

---

搜索策略（三层递进）

Layer 1: 快速路由 (~200 Token)

优先执行。匹配预置领域关键词直接定位。

执行步骤:
  1. 读取 DOMAINS.md 中的领域映射
  2. 从用户查询中提取关键词
  3. 匹配领域 → 获取 primary/secondary 文档路径
  4. 直接读取目标文档

成功条件: 关键词命中预置领域
失败处理: 进入 Layer 2

Layer 2: 架构文档搜索 (~500-1000 Token)

Layer 1 无匹配时执行。Grep 搜索架构文档。

搜索范围 (按优先级):
  1. */ARCHITECTURE.md (L0)
  2. */docs/ARCHITECTURE.md (L0)
  3. */docs/architecture/*.md (L1)
  4. shared/contracts/**/*.yaml
  5. standards/**/*.md

执行步骤:
  1. Grep 关键词搜索上述范围
  2. 读取匹配的架构文档
  3. 提取: 信息摘要 + 代码文件指针 + 相关链接

成功条件: 在架构文档中找到相关信息
失败处理: 进入 Layer 3

Layer 3: 传统搜索 (Fallback)

仅当 Layer 1+2 均失败时执行。

执行步骤:
  1. 输出: "⚠️ 架构文档中未找到相关信息，已切换到传统搜索模式"
  2. 使用 Grep/Glob 搜索项目全部文件
  3. 返回原始搜索结果

注意: Token 消耗较高，应尽量避免

---

输出格式

搜索完成后按以下格式输出：

## 🔍 架构搜索结果

**查询**: [用户搜索意图]
**搜索层级**: Layer [1/2/3]
**匹配置信度**: [高/中/低]

### 📄 相关文档

| 文档 | 相关度 | 关键内容 |
|------|--------|----------|
| `path/to/doc.md` | ⭐⭐⭐ | 简短摘要 |

### 📝 信息摘要

[从架构文档提取的关键信息，3-5 句话]

### 📁 代码文件指针

如需查看具体实现：
- `src/path/to/file.dart` - [功能描述]

### 💡 建议下一步

- [ ] 读取 `xxx.md` 了解详细设计
- [ ] 查看 `xxx.dart` 实现代码

---

工具使用权限

允许使用:
  - Grep: 搜索架构文档内容
  - Glob: 定位文档文件
  - Read: 读取架构文档
  - LS: 列出目录结构

不应使用:
  - Write/Edit: 此 Skill 仅搜索，不修改
  - Bash: 避免使用 shell 命令搜索

---

Token 节省效果

场景	传统搜索	架构搜索	节省
认证实现	~3000	~500	83%
API端点	~4000	~300	92%
数据库设计	~2500	~600	76%
平均	~2900	~860	70%

---

相关文件

• 领域映射: ./DOMAINS.md
• 共享配置: @.claude/skills/arch-common/SKILL.md
• 更新 Skill: @.claude/skills/arch-update/SKILL.md

---

最后更新: 2025-12-14 Skill 版本: 1.1.0