# Arch Search

> 通过搜索架构文档替代直接搜索项目代码，平均节省 70% Token 消耗。 使用场景：定位功能实现位置、了解模块设计、回答架构问题。

- Skill: `10cg/arch-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 10cg/arch-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/10cg/arch-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 10cg (https://skillmd.com/u/10cg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/10cg/arch-search

---


# 架构搜索

## 快速开始

### 显式触发

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

### 隐式触发

当 AI 执行开发任务时自动触发：
- 收到 "实现 XXX 功能" → 自动搜索定位代码
- 收到 "修复 XXX 问题" → 自动搜索相关模块
- 回答 "XXX 是怎么实现的" → 自动搜索架构文档

---

## 搜索策略（三层递进）

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

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

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

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

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

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

```yaml
搜索范围 (按优先级):
  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 均失败时执行**。

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

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

---

## 输出格式

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

```markdown
## 🔍 架构搜索结果

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

### 📄 相关文档

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

### 📝 信息摘要

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

### 📁 代码文件指针

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

### 💡 建议下一步

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

---

## 工具使用权限

```yaml
允许使用:
  - 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