familiarize

STARTER_CHARACTER = 🗺️

熟悉项目

不写入源代码。不使用 Agent。完成后列出读取过的文件和符号。

参数

如果用户指定了要关注的子目录或路径，将其用作 SCAN_TARGET。 如果未指定目标，则扫描整个项目根目录。

---

步骤 1：确定扫描根目录

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

如果已确定 SCAN_TARGET，将其视为子目录：SCAN_ROOT=$PROJECT_ROOT/<SCAN_TARGET>。如果路径不存在，请报告并停止。

如果未指定 SCAN_TARGET，则 SCAN_ROOT=$PROJECT_ROOT。

继续之前，说明扫描根目录。

---

步骤 2：Serena 设置

2a. 检查是否完成入门流程

调用 mcp__serena__check_onboarding_performed。

• 如果无法调用该工具，则设置 SERENA=false 并跳到步骤 3。
• 如果已完成入门流程，则设置 SERENA=true。
• 如果尚未完成入门流程，则运行 mcp__serena__onboarding 并按照其返回的说明探索项目和写入记忆文件。
• 如果任何 Serena 调用出错，则设置 SERENA=false 并继续。

入门流程完成或跳过后，立即继续步骤 2b。不要超出入门说明的要求继续探索或写入记忆。

2b. 读取现有记忆

如果 SERENA=true，调用 mcp__serena__list_memories。如果存在记忆，使用 mcp__serena__read_memory 逐一读取。这些记忆提供关于项目的既有背景信息。

继续之前，说明 Serena 是否已启用以及已加载多少条记忆。

---

步骤 3：上下文文档

3a. CLAUDE.md 文件

查找 SCAN_ROOT 下的所有 CLAUDE.md 文件（排除 .git/ 路径）。逐一读取。

find "$SCAN_ROOT" -name "CLAUDE.md" -not -path "*/.git/*" -not -path "*/node_modules/*"

3b. .llmdocs/ 目录

查找 SCAN_ROOT 下的所有 .llmdocs/ 目录。对于每个目录，读取其中的所有 .md 文件。

find "$SCAN_ROOT" -type d -name ".llmdocs" -not -path "*/.git/*"

然后对找到的每个目录执行：

ls "$LLMDOCS_DIR"/*.md

读取每个匹配的文件。

如果未找到，则静默跳过。

3c. 最近的提交

git log --oneline -20

---

步骤 4：仓库元数据

检查并读取 SCAN_ROOT 中存在的以下文件。不存在的文件直接跳过，无需说明。

配置文件

• .envrc
• .env.example
• .gitignore
• .gitattributes

包清单

• package.json
• pyproject.toml
• Cargo.toml
• go.mod
• Gemfile
• requirements.txt
• pom.xml
• build.gradle

构建和任务配置

• Makefile
• Taskfile.yml
• justfile
• Rakefile

容器

• Dockerfile（以及 Dockerfile.* 等变体）
• docker-compose*.yml

IaC（仅列出文件名，不读取内容）

• terraform/*.tf
• serverless.yml
• sam-template.yaml

CI/CD（仅列出文件名，不读取内容）

• .github/workflows/*.yml
• .gitlab-ci.yml
• Jenkinsfile
• .circleci/config.yml

文档

• 扫描根目录下的 README.md

---

步骤 5：代码结构

5a. 目录树

深度为 3，排除无关目录：

find "$SCAN_ROOT" -maxdepth 3 \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/__pycache__/*" \
  -not -path "*/vendor/*" \
  -not -path "*/.terraform/*" \
  -not -path "*/.venv/*" \
  -not -path "*/venv/*" \
  -not -path "*/dist/*" \
  -not -path "*/build/*" \
  -not -path "*/.next/*" \
  -not -path "*/target/*" \
  | sort

5b. 入口点符号

按文件名模式识别 SCAN_ROOT 下的入口点文件：

• main.*、index.*、app.*、cli.*
• __main__.py
• cmd/*/main.go
• src/lib.rs、src/main.rs
• server.*、handler.*

最多收集 5 个匹配项。优先选择更靠近扫描根目录的文件。

如果 SERENA=true：对每个匹配项运行 mcp__serena__get_symbols_overview，并将 depth 设为 2。此调用会返回顶层符号及其子项（方法、属性、嵌套类型）。如果文件返回了符号，则记录这些符号，并跳过该文件的 bash 回退操作。然后选出最重要的 1 至 2 个入口函数（例如 main、run、createApp、setup），调用 mcp__serena__find_symbol 并将 include_body 设为 true，以读取其实现。这有助于了解初始化顺序、依赖连接方式和启动流程。

如果 SERENA=false，或者 Serena 对某个文件返回空结果或出错，则读取该文件的前 80 行。

5c. 架构符号搜索（仅限 Serena）

如果 SERENA=false，请跳过此步骤。

使用 mcp__serena__find_symbol 查找常见的架构符号。通过 relative_path 参数将每次搜索的范围限定在 SCAN_ROOT。使用 include_body: false 和 depth: 1。

搜索以下 name_path_pattern 值（无结果时跳过）：

• main
• app
• server
• router
• handler
• config
• middleware
• schema
• model

find_symbol 调用总数最多为 10 次。如果架构形态已明确，则提前停止。

对于找到的关联度最高的 2-3 个符号（出现在多个文件中或有许多子项的符号），可以选择调用 mcp__serena__find_referencing_symbols，以梳理哪些内容会调用它们。此工具需要同时提供 find_symbol 结果中的 name_path（例如 MyClass/my_method）和 relative_path（定义该符号的文件）。

引用查找最多进行 3 次。

5d. 源文件符号映射

根据 5a 中的目录树确定源代码目录（包含源文件，而非配置、文档或测试文件的目录）。

如果 SERENA=true：对每个目录中最多 5 个有代表性的源文件运行 mcp__serena__get_symbols_overview，并设置 depth: 2。记录类名、函数名、接口名和方法签名。如果文件未返回任何符号（语言不受支持或发生错误），则改用 bash 检查该文件。

如果 SERENA=false，或 Serena 未返回某文件的结果：读取该文件的前 80 行。

两种路径都跳过以下文件：

• 测试文件（*_test.*、*.test.*、*.spec.*、test_*）
• 生成文件（*.min.js、*_pb.go、*.generated.*、*.g.dart）
• 锁文件（package-lock.json、yarn.lock、poetry.lock、Cargo.lock）

5e. 类型和接口清单

使用 mcp__serena__find_symbol 查找关键类型定义。通过 relative_path 将搜索范围限定在 SCAN_ROOT，并使用 include_body: false 和 depth: 1 搜索以下 name_path_pattern 值：

• interface
• type
• enum
• struct
• dataclass
• schema
• dto

调用总数最多为 7 次。对于找到的最核心的 2-3 个类型（在入口点中被引用或出现在多个文件中的类型），调用 mcp__serena__find_symbol 并设置 include_body: true，以读取其完整定义。这有助于了解驱动项目的领域模型和数据形态。

如果 SERENA=false，请跳过此步骤。

5f. 测试结构

根据 5a 中的目录树确定测试目录和文件：

• 名为 test/、tests/、spec/、__tests__/ 的目录
• 匹配 *_test.*、*.test.*、*.spec.*、test_* 的文件

列出找到的所有测试文件。然后选取 2-3 个有代表性的测试文件：

如果 SERENA=true：运行 mcp__serena__get_symbols_overview 并设置 depth: 1，以查看测试函数和类名。

如果 SERENA=false：读取前 60 行。

记录：使用的测试框架（根据导入和断言推断）、测试命名惯例、测试属于单元测试还是集成测试风格，以及存在的测试工具或 fixture。

---

第 6 步：报告

输出两个部分：

已读取的文件和符号

按步骤分组，列出已读取的所有文件和发现的符号。对于 Serena 的结果，列出文件路径和统计摘要（例如“3 个类、12 个函数、2 个接口”）。对于通过 bash 检查的文件，只列出文件名。

概述

基于阅读的所有内容总结项目。按顺序涵盖以下三个部分。总共写 10—14 段正文。概述中不要使用项目符号或标题。

工作原理（机制说明）：

• 项目的功能
• 技术栈和主要依赖项
• 代码的组织方式（关键目录及其作用）
• 公共 API 的范围和主要抽象（类、接口、导出函数）
• 领域模型和核心数据类型（根据类型／接口清单）
• 模块之间的关系和依赖流向（根据引用查询和入口点函数体）
• 代码中体现的约定或模式（命名、错误处理、分层）
• 测试策略（测试框架、覆盖方式、测试组织）

重要性（价值和目的）：

• 项目解决的问题及其面向的用户
• 有哪些替代方案，以及本项目有何不同（根据 README、文档或代码模式推断）
• 代码中体现的架构权衡（优先考虑了什么，推迟了什么）
• 观察到的技术债务或维护风险（缺少测试、依赖项过时、边界不明确）
• 值得注意、缺失或不明确的内容

使用方法（快速入门）：

• 如何构建（构建系统、编译步骤、依赖项安装）
• 如何运行或安装（入口点、启动命令、部署方式）
• 如何测试（测试框架、测试命令、测试位置）
• 新贡献者需要了解的关键工作流（开发流程、常见任务）
• 配置选项和环境要求

报告完成后，等待指示。