• AI 应用
• AI 技能

导读

/expand是 ai-job-search 项目（基于 Claude Code 的 AI 求职申请框架）中的一条核心命令，用于从候选人已有的文档与公开在线足迹中发现并增量扩充能力画像。本文以 .claude/commands/expand.md 为骨架，结合 tests/test_expand_command.py 的契约测试与 .claude/skills/job-application-assistant/SKILL.md 的技能框架，完整讲解其 6 步执行流程、双轨网络增强方法、能力地图的六类分组、用户确认机制与"纯增量、可溯源、幂等"的三条工程底线。读完本文，你将掌握如何在/setup之后立即运行/expand，把简历、LinkedIn 导出、学位证、推荐信与 GitHub 仓库中隐含的技能信号系统性地挖掘出来，并以带来源标注的方式写回档案。

一、命令定位：/expand在整个求职框架中的角色

在 ai-job-search 中，候选人信息的主仓库是.claude/skills/job-application-assistant/下的两份档案文件：

• 01-candidate-profile.md：承载身份、教育、工作经历、独立项目、技术技能、论文、奖项与推荐人；
• 02-behavioral-profile.md：承载行为测评、核心驱动力、最强特质、理想工作方式与成长区。

这两份档案由/setup命令从documents/目录中的原始材料（简历、LinkedIn 导出、学位证、推荐信、项目文档）生成。但正如 README.md 所述，/setup只提取文档中明确写出的内容；而候选人的能力往往还"隐藏"在公开在线足迹中——GitHub 仓库的技术栈、未置顶仓库、课程/证书的官方 syllabus、推荐信里的措辞。/expand正是为此而生：它扫描你已关联的公开来源（GitHub 仓库、作品集站点、Kaggle、Google Scholar），并查询具名课程与证书的教学大纲，把发现的能力以带来源标签的方式追加进档案。

项目的 CHANGELOG.md 将该特性记录为 "/expandproject and portfolio expansion"，其定位是 "expands candidate discovery"，且配套了独立的契约测试文件，说明这条命令是框架的正式组成部分而非临时脚本。

何时使用：README 建议在/setup之后立即运行一次，用于浮出"仅凭文档无法显性化"的技能面。此后每次新增证书、课程或公开项目时，可随时重跑——命令本身被设计为幂等的（见下文"来源标注"机制）。

二、总体工作流：六步严格顺序

/expand的命令文档明确要求"Follow these steps exactly in order. Do not skip steps"。完整链路如下：

契约测试 test_expand_command.py 对命令规范做了机器可验证的约束：文件必须以# /expand开头、必须覆盖全部五类本地发现源、必须把 GitHub 项目映射到Independent Projects章节、必须强制"纯增量"与"先确认再写入"原则。这些测试实际上把命令的设计承诺固化成了可回归的规范——后续任何对 expand.md 的修改都不得破坏这些承诺。

三、Step 0：先读档案，全程持有，杜绝重复

命令的第一步是并行读取两份档案：

• .claude/skills/job-application-assistant/01-candidate-profile.md
• .claude/skills/job-application-assistant/02-behavioral-profile.md

读取后这些内容必须"全程保持在上下文中"，且后续步骤不得重复读取。这一设计有双重意图：

1. 去重基准：Step 1 发现的任何经验项，都要与档案已有内容比对；已存在的能力在 Step 3 被移除，从而保证all确认不会产生重复条目。
2. 上下文一致性：Step 5 写入时必须"追加到对应章节并匹配既有结构"，这要求写入时刻仍清楚档案原貌——例如01-candidate-profile.md的独立项目区格式为- **[PROJECT_NAME]**: [DESCRIPTION]，新条目必须沿用该格式而非另起炉灶。

从01-candidate-profile.md的模板可以确认档案的章节骨架：Identity、Education、Professional Experience、Independent Projects、Technical Skills（含Programming & ML/Domain Expertise/Software & Tools三个子区）、Publications、Awards、References；02-behavioral-profile.md则包含Overview、Core Behavioral Drives、Strongest Behaviors、How You Work Best、Growth Areas、Mapping to Job Posting Language、Management Style Preferences、Using This in Applications。这些章节正是 Step 5 追加目标位置的依据。

四、Step 1：六路信息源的全源发现

命令按固定顺序扫描所有可用来源，对每个来源提取"经验项"（experience items）——任何暗示技能、知识或能力的素材。

1a.documents/cv/— 主简历

按 documents/README.md 的说明，该目录存放最完整、未经裁剪的主简历（支持.pdf与.tex）。此处提取五类信息：

• 每一门课程或模块（含大学课程与在线课程）；
• 每项认证及其颁发机构和日期；
• 每一条工作职责要点（工具、方法、成果）；
• 每个独立项目或副业项目；
• 每个志愿或课外角色。

1b.documents/linkedin/— LinkedIn 导出

该目录存放 LinkedIn "Save to PDF" 导出的结构化档案（仅.pdf，多份时取最近修改者）。提取项包括：Licenses & Certifications区的课程与认证、技能与认可列表、志愿经历、项目区，以及任何CV 中尚未出现的平台特有项——这正是"文档单独无法显性化"信息的典型来源。

1c.documents/diplomas/— 学位证书与成绩单

提取成绩单上列出的所有课程/模块名称、论文题目与研究领域、专业方向或轨（track）名称。该目录的文件命名（如msc_physics_ucph_2025.pdf）不影响解析。

1d.documents/references/— 推荐信

推荐信的价值在于第三方措辞。命令要求提取：推荐人使用的能力语言（他们提到哪些技能与品质）、以及点名提到的具体项目、工具或方法。这类内容天然已是"能力表述"，Step 2 无需再做网络查找，直接记录即可。

1e. GitHub Profile — 全量仓库扫描

从01-candidate-profile.md的Identity区取得 GitHub 用户名或 URL，然后：

1. 用 WebFetch / WebSearch 获取公开主页与置顶仓库；
2. 对每个仓库：抓取 README，记录名称、描述、主要语言、主题/标签，以及 README 中点名的框架与库；若该仓库是独立的真实技术项目（非空壳 stub、非未定制的 fork），则提取项目摘要（问题域、技术栈、可验证的技术成果）归入 Independent Projects；
3. 额外拉取完整仓库列表以捕获未置顶仓库——命令明确强调"unpinned repos often contain significant competency signals"，因为能力信号未必出现在置顶位。

若档案中找不到 GitHub 用户名/URL，则跳过该来源并明确记为 skipped，绝不编造。

1f. 档案中的其他 URL

检查01-candidate-profile.md中是否有其他链接（作品集、个人网站、Kaggle、Google Scholar、ResearchGate、论文链接），逐个抓取页面并提取提到的工具、方法、数据集、奖项与技能。

契约测试test_expand_covers_all_discovery_sources断言命令文本必须同时包含documents/cv/、documents/linkedin/、documents/diplomas/、documents/references/与GitHub Profile五类本地源；同时test_expand_maps_github_projects_to_independent_projects_section断言不得依赖documents/projects/目录——即 GitHub 发现的项目走独立通道进入档案，与本地项目文档互不混淆。

五、Step 2：双轨网络增强——直接查找 × 能力推断

对 Step 1 发现的每个经验项，命令要求同时应用两种增强方法，"do not choose one over the other"：

方法 A：直接查找（显式工具与框架）

若经验项点名了具体工具、框架、库、方法或平台，直接检索其官方能力清单，典型查询模板：

• "[Course name] [Provider] syllabus learning outcomes"
• "[Certification name] skills covered exam guide"
• "[Tool/framework name] skills what you learn"

取最相关页面，抽取能力列表。

方法 B：能力推断（从描述与上下文出发）

无论方法 A 是否命中，都从经验项本身的描述出发推理三个问题：

• 该经验项解决什么问题域（problem domain）？
• 完成这类工作需要哪些方法、技能或知识？
• 这类工作的标准工具链（standard toolchain）是什么？

两种方法的结果合并为每个经验项的唯一能力列表。

优先级指引

命令还给出了"查什么、不查什么"的明确分界：

这一"查网络 + 做推断"永不二选一的约束，在02-behavioral-profile.md的模板中有呼应：该档案的 Overview 区注明测评结果可来自 PI、DISC、Myers-Briggs、StrengthsFinder 或自评，与/expand把"间接信号"与"显式测评"并重的取向一致。

六、Step 3：构建去重能力地图

所有经验项增强完成后，按以下六类分组：

1. Technical Skills — Primary：日常工作常用的核心语言、框架、方法；
2. Technical Skills — Secondary：用过但不作为主力的工具；
3. Domain Knowledge：领域专长（如地球物理、ML、NLP）；
4. Methods and Practices：敏捷、版本控制、可复现性、测试等实践；
5. Soft / Behavioral：来自推荐信与项目描述的领导力、沟通、协作信号；
6. Independent Projects & Portfolio：来自 GitHub 的独立技术项目，含问题域、技术栈与关键技术里程碑。

每个能力条目必须记录三项元数据：能力名称、来源项（例如Coursera — Deep Learning Specialisation、GitHub — repo-name、Reference letter — Jens Jensen）、以及来源方式（方法 A 直接查找 / 方法 B 推断 / 两者兼有）。

每个项目条目记录：项目名、一行摘要（解决的问题 + 技术栈 + 可验证的成果/影响）、来源（如GitHub — repo-name）。

最后，移除 Step 0 档案中已存在的任何内容——这一步完成去重，是"不产生重复"承诺的落点。

七、Step 4：分组摘要与用户确认

在写入任何文件之前，命令以固定格式呈现全部新增能力供用户审阅，格式模板如下：

## /expand found [N] new competency signals across [M] sources **COURSES & CERTIFICATIONS** Source: [Course/cert name — Provider] + [Competency 1] + [Competency 2] **PROJECTS & PORTFOLIO** Source: [GitHub — repo-name] + [Project Name]: [Problem, stack, and outcome] **GITHUB — [repo-name]** Source: README + inferred from tech stack + [Competency 1] **JOB RESPONSIBILITIES — [Company, Role]** Source: CV bullets + direct tool lookup + [Competency 1] **BEHAVIORAL SIGNALS** Source: [Reference letter — Name / LinkedIn About / Project leadership] + [Signal 1]

随后命令必须等待用户响应，提供三个选择：

• all— 将以上全部加入档案
• review— 逐个来源分组逐一过目
• skip— 取消且不写入任何内容 或列出要跳过的具体分组（例如 "skip GitHub, add everything else"）。

契约测试test_expand_enforces_additive_and_confirmation_principles断言命令文本必须同时包含all、review、skip三个选项与Additive only、User confirms before writing两条原则——确认机制是被测试固化的硬性承诺。这一"先呈示、后落盘"的设计，使能力扩充始终处于候选人的知情控制之下。

八、Step 5：写入确认项——纯增量、带来源、幂等

确认后，命令仅对确认项执行Edit 工具的追加操作，绝不重写整个文件（"Use the Edit tool to add to the relevant sections of each file — do not rewrite entire files"）。

对01-candidate-profile.md的追加规则

• 独立项目 → 追加到## Independent Projects，格式为- **[Project Name]**: [Description with stack and outcome] *(GitHub — repo-name)*；
• 技术技能（主/次）→ 追加到 Technical Skills 区；
• 领域知识 → 追加到 Domain Knowledge 或 Technical Skills 区（匹配既有结构）；
• 方法与实践 → 相应位置追加。

每一条新增都附带来源标注，放在注释或括号中，例如*(Coursera — Deep Learning Specialisation)*、*(GitHub — project-name)*。这一标注是幂等性的关键：后续再次运行/expand时，Step 0 的档案内容 + 来源标注即"去重基准"，同一来源的同一能力不会重复追加。

对02-behavioral-profile.md的追加规则

• 软性/行为信号 → 追加到Strongest Behavioral Traits或How I Work Best（匹配既有结构）；
• 推断型行为信号必须强制标注：*[Inferred from reference letter — Name / review before relying on this]*。

这一标注规则呼应了档案模板中的Don't overstate一节——行为信号尤其容易过度解读，命令通过强制标注让候选人对"推断来的特质"保持批判性审视。

九、Step 6：总结报告

写入完成后输出结构化报告，包含五个板块：

## /expand Complete ### Added to 01-candidate-profile.md [每项新增能力/项目及其来源] ### Added to 02-behavioral-profile.md [每项新增行为信号及其来源] ### Sources processed [每个扫描过的来源及其产出的能力数量] ### Sources skipped [缺失、为空或未产出新增项的来源，附简要原因] ### Needs manual review [含糊、部分可读、或网络查找未返回清晰大纲的条目]

Sources skipped板块与 Step 1 的"跳过来源须显式记录"构成闭环——全流程对每个来源都有处置痕迹；Needs manual review板块则把"无法确认的事实"显式移交人工，与项目SECURITY.md强调的"未验证内容不得当事实使用"的安全取向一致。

十、七条设计原则：命令的工程契约

命令文档末尾以 "Design Principles" 形式固化七条约束，它们共同定义了/expand的行为边界：

1. 纯增量（Additive only）：永不修改既有档案内容，只追加；
2. 来源可溯源（Source-traceable）：每条新增都记录出处，使后续运行幂等，且用户可逐条验证或移除；
3. 双轨永不二选一（Both approaches, always）：具名课程同时获得官方 syllabus 与推理能力列表；
4. 先确认后写入（User confirms before writing）：完整能力地图在触碰任何文件前先展示并获确认；
5. 行为信号必须标注（Behavioral signals are labeled）：从语气、语言或间接信号推断的内容一律标记为 inferred；
6. GitHub 全量扫描（GitHub is fully scanned）：检查全部公开仓库，不限于置顶——未置顶仓库常含重要能力信号；
7. 项目以代码为锚（Portfolio & projects grounded in code）：写入档案的独立项目必须来自公开 GitHub 仓库中的真实项目，绝不虚构项目声明。

这些原则在 tests/test_expand_command.py 中被逐条断言：文件存在性与首行格式、五类发现源覆盖、GitHub→Independent Projects 映射（且不误用documents/projects/）、all/review/skip与增量/确认原则的强制包含。测试即规范，规范即测试，这保证了命令文档在项目演进中不被悄然破坏。

十一、与框架其他模块的协同

从 .claude/skills/job-application-assistant/SKILL.md 的参考文件表与 documents/README.md 可以看清/expand在框架中的上下游关系：

• 上游是/setup：documents/目录是/setup的输入，也是/expand四类本地来源的输入；/setup生成的两份档案文件是/expand的读取基准与写入目标；
• 下游是求职产出链路：扩充后的档案被04-job-evaluation.md（岗位匹配打分）与05-cv-templates.md/06-cover-letter-templates.md（定制 CV 与求职信）消费——能力地图越完整、来源越可信，后续匹配与定制就越精准；
• 数据血缘一致：documents/README.md明确projects/目录的项目摘要同样汇入01-candidate-profile.md的## Independent Projects，与/expand的 GitHub 通道殊途同归，但契约测试刻意把两者分开，避免来源混淆。

值得一提的边界是 .claude/settings.json：工作区权限清单中并未给/expand配置任何 Bash 白名单，说明该命令的设计意图是纯工具类操作（Read、Glob、Grep、WebFetch、WebSearch、Edit、Write、AskUserQuestion 均属 Claude Code 内置能力），不依赖外部 CLI，因此在任何允许该 Skill 的会话中都可直接运行，无环境前置要求。

结语：把"能力发现"变成可审计的工程流程

/expand的独特之处在于它把求职场景中最模糊的一步——"我到底还有哪些技能没写出来"——变成了一条步骤严格、双轨证据、用户确认、逐条溯源、测试护航的流水线。从 .claude/commands/expand.md 的命令规范到 tests/test_expand_command.py 的契约断言，每一层都在回答同一个问题：如何在不虚构、不重复、不越权的前提下，把候选人文档与公开足迹中的能力信号完整地、可验证地沉淀进档案。对任何 fork 并使用 ai-job-search 的求职者而言，/setup之后的第一件事，就是运行/expand。

• AI 应用
• AI 技能