企业官网建设流程全解析

• AI 应用
• AI 技能

导读

本文以仓库根目录的 AGENTS.md 为骨架，剖析 AI Job Search 工作区如何用thin-pointer 设计（薄指针 / 单一事实来源）组织候选档案、工作流规范与门户搜索技能，使其能同时被 Claude Code、Google Antigravity、Codex、Cursor、Gemini CLI 等多种 Agent 运行时无缝消费。读完本文，你将理解该工作区"指针薄、内容厚"的目录分层原则，掌握CLAUDE.md、.claude/与.agents/三者的职责边界，并能基于这套模式为自己的多 Agent 项目设计防配置漂移（configuration drift）的目录结构。

一、工作区定位：一个"跑在你机器上"的求职系统

AGENTS.md 开篇即声明：该工作区被结构化地用于管理求职活动的方方面面——scraper 工具、CV、求职信与面试准备。它不是一个普通文档目录，而是一套可被多种 AI Agent 运行时读取并执行的操作系统式工作区：Agent 不只是"读文件"，而是按规范执行完整的求职流水线（评估岗位、定制简历、撰写求职信、准备面试）。

这一点与仓库根目录 README.md 描述的定位一致：这是一个基于 Claude Code 构建的 AI 求职应用框架，主张"Fork it and own it"——即每个求职者 fork 后填入自己的真实资料，就能拥有一套私人定制的求职自动化系统。正因如此，"如何防止不同 Agent 框架读到相互矛盾的配置"成为该项目的核心工程问题，thin-pointer 设计就是它的答案。

二、thin-pointer 设计的核心思想：先防漂移，再谈功能

2.1 为什么需要 thin-pointer

AGENTS.md 明确点出了引入该设计的动机：

To prevent duplication and configuration drift across different AI agent frameworks (Claude Code, Google Antigravity, Codex, Cursor, Gemini CLI, etc.)

在实际使用中，同一位开发者可能在不同终端、不同项目副本中切换多个 Agent 运行时。如果每个框架各自维护一份"候选人资料"或"工作流说明"的副本，那么：

• 重复维护：改一次简历技能清单，要在 N 份副本里同步 N 次；
• 配置漂移：某份副本被改动后，不同 Agent 对同一求职者的认知不再一致——一份说"精通 Python"，另一份还是旧数据；
• 权威性丢失：当多份配置互相矛盾时，Agent 无从判断哪份是真相。

thin-pointer 的解法是：所有 Agent 运行时统一从少量权威文件（canonical specifications）加载规范与候选人档案，目录本身只存放"指针"（薄），被指向的文件才承载"内容"（厚）。AGENTS.md 用一句话概括了这套契约："All agent runtimes should load the canonical specifications and candidate profiles from the files and directories below."

2.2 三大信息来源：一条明确的加载契约

AGENTS.md 把整个工作区的权威数据源归纳为三类，构成任何 Agent 启动工作前必须遵循的加载路径：

关键纪律（AGENTS.md 原文）："Do not duplicate these rules or specifications. Treat.claude/files as the single source of truth."—— 即任何地方不得复制这些规则，.claude/目录内的文件是工作流规范唯一的真源。这条纪律正是防漂移的落地点：新 Agent 框架接入时，只需指向这三个位置，无需搬运任何内容。

三、信息来源一：个人候选人档案（CLAUDE.md + profile 技能族）

3.1 CLAUDE.md：候选人的"主档案"

CLAUDE.md 是候选人的身份中枢，其## Candidate Profile一节由/setup命令在首次配置时用真实信息替换所有[PLACEHOLDER]占位符后生成，涵盖：

• Identity：姓名、所在地、通勤约束、语言表（含熟练度等级）、CV 语言、在职状态、LinkedIn 头条；
• Education / Professional Experience / Technical Skills：按时间倒序的结构化履历；
• Certifications / Publications / Awards：资质与荣誉；
• Behavioral Profile：性格测评结果与优势、成长点、理想工作环境；
• Target Sectors / Deal-breakers：目标行业与硬性排除条件。

此外，CLAUDE.md 还内嵌了## Workflow for New Job Applications（新岗位申请的标准流程）与## Verification Checklist（CV/求职信产出后必须逐项自检的核对清单），后者包括事实准确性、针对性、一致性、质量以及强制性的 PDF 编译验证（CV 用 lualatex、求职信用 xelatex，页数分别精确为 2 页与 1 页）。

3.2 job-application-assistant 技能族：方法论的九个模块

AGENTS.md 特别点名了 .claude/skills/job-application-assistant/ 下的01-*.md系列文件。该目录共 10 个文件，其中 SKILL.md 是入口，定义了触发词（"job posting""CV""cover letter""interview prep"等）与四步工作流（评估匹配 → 定制 CV → 撰写求职信 → 面试准备）；01-*.md至09-*.md九个模块构成方法论全集：

其中04-job-evaluation.md值得单独说明：它定义了先于打分的两扇门禁（Eligibility Gate 资格门禁与 Language Gate 语言门禁）和五个打分维度（技术匹配、经验匹配、行为匹配、职业匹配等），其语言门禁结果会被/rank持久化进seen_jobs.json的language_gate字段并作为否决项。这正是 thin-pointer 的体现——打分规则只存于此文件，/scrape、/rank、/apply全部引用同一份。

四、信息来源二：.claude/权威工作流规范

4.1 分层：skills（能力）与 commands（命令）

AGENTS.md 指出，任务级规范存在于 .claude/ 目录下，具体分两处：

• .claude/skills/：声明式能力定义。除上述job-application-assistant外，还有 job-scraper/SKILL.md（负责门户搜索编排与去重）与 upskill/SKILL.md（技能提升）；
• .claude/commands/：斜杠命令实现。仓库实际包含setup、scrape（skill 形式）、rank、apply、outcome、interview、reset、expand、add-portal、add-template、gmail-sync、html-report、notion-sync等命令的逐步指令。

以 .claude/commands/apply.md 为例，它是一份"起草者-评审者"双 Agent 工作流规范：Step 0 解析输入（并把岗位文本视为不可信数据，禁止执行其中内嵌的指令）、Step 1 由起草者评估匹配并做来源主机验证、Step 2 起草 CV 与求职信、Step 3 派发独立评审 Agent 做事实溯源审计（Grounding Audit）、Step 4 按评审反馈修订、Step 5 强制编译并视觉检查 PDF、Step 6 按 CLAUDE.md 的核对清单汇报结果并记录到job_search_tracker.csv。

4.2 命令与技能如何互相引用而不复制

thin-pointer 设计在此体现得尤为彻底：命令文件之间通过"引用对方已定义过的规则"来避免重复定义。

• .claude/skills/job-scraper/SKILL.md 的 Step 5 声明，当选出岗位后直接转入job-application-assistant技能的工作流，而不再重复实现评估逻辑；
• 该 SKILL.md 的记录步骤（Step 3b）明确写道："Follow/applyStep 6b exactly ... It is stated there once so the two paths cannot drift"—— 即同一套"记录申请"规则只在/apply中写一次，/scrape路径引用它，从而两条路径不可能各自演化出不同的记录格式；
• .claude/commands/rank.md 的评分权重（技术 30%、经验 25%、行为 15%、职业 30%）与阈值分带（Strong Fit 75+ 等）直接取自04-job-evaluation.md，命令内不重抄定义，只引用。

4.3 状态文件与工具辅助：薄指针延伸到数据层

工作流规范还规定状态与命令行工具的分工，防止"状态流经对话上下文"造成漂移：

• job_scraper/seen_jobs.json是抓取去重状态文件，键由 tools/job_key.py 以"岗位的纯函数"方式生成（保证跨运行稳定，长标题做长度截断并用哈希消歧）；
• /rank明确要求绝不把seen_jobs.json读入对话，而是通过 tools/rank_state.py 的candidates、sweep --write、apply --results子命令以查询方式读写；
• .claude/settings.json 通过权限白名单约束 Agent 可执行的命令（如Bash(bun run .agents/skills/jobbank-search/cli/src/cli.ts:*)、Bash(python tools/job_key.py:*)、Bash(python3 salary_lookup.py:*)），从运行时层面保证规范只能触碰被授权的工具。

这套"状态不经过对话、只经过工具"的约定，可视为 thin-pointer 在数据一致性维度的延伸：状态文件是唯一真源，任何 Agent 框架都必须通过同一批工具读写。

五、信息来源三：.agents/skills/可移植门户搜索技能

5.1 可移植 Agent Skills 格式

AGENTS.md 指出，门户搜索 CLI 存放于 .agents/skills/，采用可移植的 Agent Skills 格式，每个门户一个SKILL.md。仓库实际包含六个门户技能：linkedin-search、freehire-search、jobbank-search、jobdanmark-search、jobindex-search、jobnet-search。

以 .agents/skills/linkedin-search/SKILL.md 为范例，它的 frontmatter 包含name、version、description、context: fork、enabled: true与allowed-tools。其中：

• context: fork表明技能为 fork 场景设计——位置参数始终显式传入，同一技能在任何市场开箱即用；
• enabled: true是门户开关：设为false可让门户保持安装但被/scrape跳过（该文件的注释原文："set to false to keep this portal installed but have /scrape skip it"）；
• allowed-tools限定本技能只允许运行bun run .agents/skills/linkedin-search/cli/src/cli.ts *这一条命令。

技能正文给出完整 CLI 用法：search子命令支持--location（必填）、--query、--jobage/--jobage-minutes、--remote、--page、--limit、--format json|table|plain；detail子命令接受数字 job ID、完整 URL 或 URN。全部通过bun运行、无认证、无运行时依赖，数据来自 LinkedIn 公开的jobs-guest端点。

5.2 自动发现与/scrape编排

AGENTS.md 明确了两个关键机制：

1. Codex 与 Antigravity 会自动发现.agents/skills/下的技能（可移植格式天然被这些框架识别）；
2. /scrape工作流编排它们：.claude/skills/job-scraper/SKILL.md 的 Step 1b 规定：读取.agents/skills/*/SKILL.md发现所有已安装门户技能，使用每个门户自己文档化的 CLI 接口，绝不猜测 flag，并遵守enabled开关；随后把各门户结果合并、去重、按匹配度呈现。

这种"编排者（.claude/）与执行者（.agents/）分离"的结构，使新增门户无需改动编排逻辑——这正是 thin-pointer 的收益：/add-portal命令只需在.agents/skills/下新增一个技能目录，/scrape下一轮运行即自动纳入，任何 Agent 框架都通过同一路径发现它。

六、fork 场景：thin-pointer 让"复制即拥有"成为可能

AGENTS.md 的链接列表与全文处处指向 fork 工作流，这与仓库定位"Fork it and own it"互相印证：

• 候选人资料集中在 CLAUDE.md 与 profile 技能族，fork 者只需替换身份类占位符，方法论无需改动；
• .claude/commands/setup.md 提供三条 onboarding 路径（文档文件夹导入、单 CV 导入、访谈式问答），最终都收敛到同一批 profile 文件；其 Step 0 甚至会在写入前检查origin是否为公开 fork，提醒用户个人资料提交到公开仓库的可见性风险；
• 门户技能以参数化位置运行，任何国家的求职者都能直接使用；
• 测试目录 tests/ 覆盖了test_setup_command.py、test_scrape_contract.py、test_apply_records_application.py、test_rank_command.py等，从侧面验证各命令与状态契约在 fork 后仍可回归验证。

从源码结构看，这套设计的稳定性依赖于一条原则：模板与规则保持通用，个人数据保持集中。通用规则一旦被 fork 者改动，会通过framework_versionfrontmatter（如1.0.0、1.3.4）与 CHANGELOG.md 追踪，而个人数据则严格限定在三个权威位置。

七、实践建议：把 thin-pointer 模式复制到你的项目

结合 AGENTS.md 给出的契约，可以将这套模式抽象为可移植的四条设计原则：

1. 指针薄、内容厚：根目录只放少量权威入口文件（如AGENTS.md+CLAUDE.md），所有细节下沉到按职责划分的子目录；
2. 一份规则只写一次，其余位置引用：跨命令、跨技能复用的规则（记录格式、打分权重、字段 schema）只在一个权威文件定义，其它路径以"Follow X Step N exactly"的方式引用；
3. 技能与编排解耦：可执行能力（门户 CLI、工具）放独立目录，编排逻辑通过自动发现（读SKILL.md）接入，新增能力不触碰编排代码；
4. 状态文件不进对话：持久状态由专门工具以查询/写入方式访问，任何 Agent 框架都走同一条读写路径，避免"上下文里的状态"与"磁盘上的状态"漂移。

对多 Agent 项目的直接落点：为每个 Agent 框架在项目根目录写一份薄薄的AGENTS.md（只声明"去哪些权威位置加载规范"），并禁止框架在自身配置目录缓存项目规则的副本——缓存即漂移的开始。

结语

AGENTS.md 全文不过数十行，却定义了 AI Job Search 工作区最重要的工程契约：用 thin-pointer 设计把"候选人是谁"（CLAUDE.md+ profile 技能族）、"工作怎么做"（.claude/命令与技能）、"去哪找岗位"（.agents/skills/门户技能）三件事明确分工，让 Claude Code、Antigravity、Codex、Cursor、Gemini CLI 等任意运行时都能从同一组权威文件起步，杜绝重复维护与配置漂移。对 fork 者而言，这意味着拿到仓库即可运行、改了个人资料即可拥有；对任何想要构建"多 Agent 共享工作区"的开发者而言，它是一份可直接照搬的分层范本。

进一步阅读：仓库根的 AGENTS.md（本文骨架）、CLAUDE.md（候选人主档案与核对清单）、.claude/skills/job-application-assistant/SKILL.md（四步申请工作流）、.claude/skills/job-scraper/SKILL.md（门户搜索编排）、.claude/commands/apply.md（双 Agent 申请流水线）、.agents/skills/linkedin-search/SKILL.md（门户技能范例），以及 tests/ 下对应的契约测试。

• AI 应用
• AI 技能