# 设计思路与理念

这篇讲清楚两件事：这套工具解决了什么问题，以及为什么做成现在这个样子。
给两类人看：用它的人，和想照着改一套自己版本的人。

## 一、要解决的四个问题

### 1. 用它的人不是程序员

这套工具是给 HR 和猎头用的。不能指望他们会挑 CLI（命令行工具——不点鼠标、靠打字输命令操作的程序）、会搭文件夹结构、会判断"AI 说得对不对"。
也不能指望他们都用同一款 AI 工具——Claude Code、Codex、workbuddy、qoderwork、MiniMax Code、Z code 都有可能，水平还参差不齐。

**所以：能替用户准备的，全部提前准备好。**
- 要装什么工具，已经替你选好了（boss-cli 和 liepin-cli，两个招聘平台的自动化 CLI，一条命令装完）；
- 文件夹怎么建、模板长什么样，已经做好了；
- skill（可以理解成给 AI 的工作说明书，一个文件夹装一套流程）也是现成的，初始化时自动放进你的工作文件夹。

从下载到开始干活，中间没有任何一步需要用户自己做技术判断。说一句"帮我初始化"，剩下的 AI 照着说明书走。

### 2. "我要一个厉害的人"筛不了任何简历

用人的人说需求，十有八九是这种话："找个资深的，最好懂 AI。"
这句话没法用来筛简历——几年算资深？懂 AI 是会用工具就行，还是要能干活？
拿模糊的标准去跑自动化，结果就是：AI 筛得飞快，错得也很稳定——自信地放进错的人，自信地毙掉对的人。而且报告写得很漂亮，你看不出来它错了。

**所以：自动化之前，先把标准问清楚。**
工具里有个"梳理岗位"的环节：AI 先读已有资料，把前提已经确定、可以独立回答的关键问题放在同一轮，每题给出有依据的建议。用户可以按编号确认或修改；依赖前面答案的问题，等回答后再跟进。这样把"要个厉害的"变成能执行的标准：哪些约束必须满足、哪项能力缺了就不对口（这项我们叫"命脉"）、如何验证、什么样的简历看着像其实不对。
问题参考用来查漏，不是必须逐项填完的问卷。标准够用就收口，目标公司、搜索词和渠道先由 AI 拟定并在寻源中验证。用户没想清楚的项标待定；关键标准未确认时先留草稿，不把猜测变成自动筛人的依据。

### 3. 日常招聘是重复劳动，但里面混着"点了就收不回"的动作

查未读消息、搜人、看简历、打分——纯重复劳动，AI 干最合适。
但同一条流水线里有两个动作性质完全不同：**打招呼**（打扰的是真人）和点**"不合适"**（拒掉的也是真人）。这类动作我们叫"对外不可逆动作"——点出去就收不回来。让 AI 全自动点，迟早出事故——它替你拒错一个人，你连知道都不会知道。

**所以：能撤销的放开跑，不能撤销的等人拍板。**
- 取数、筛选、记录、写报告：AI 全自动；
- 打招呼：默认先问你。你说"今天合适的直接打"，它今天就放开打，但打了谁一个个报给你，明天授权自动失效；
- 点"不合适"：**永远不自动点**。AI 觉得谁不行，先记在台账里等你确认；
- 碰到验证码、风控提醒、付费弹窗：立刻停手来问你。

### 4. 数据锁在招聘平台里，换个工具就归零

你在 Boss 上聊过的人，记录在 Boss 的服务器上；你对每个人的判断，散在聊天记录和脑子里。平台改版、换 AI 工具、换电脑，积累就没了。

**所以：所有数据都存在你自己电脑的文件夹里，而且是最普通的文本文件。**
台账是一张 CSV 表格（Excel 能开，记事本也能开），候选人档案是 Markdown 文档（就是纯文本）。从飞书邮箱收到的简历附件也会下载到工作区 `runtime/resumes/`，用邮件/附件 ID 和文件 hash 去重。飞书文档那些只是"给老板看的展示版"，从台账生成，删了能再生成。
这样做的好处：数据在你手里，可以备份、可以拷走、可以换任何工具接着用。还有一个隐藏好处——AI 每次新对话都是失忆的，但它每次干活前都会先读你文件夹里的标准和台账，等于把记性存在了文件里。

## 二、几个关键的技术决策

### 不绑定任何一家 AI 工具

各家 AI 工具都有自己的"插件"和 skill 发现机制，目录约定互不兼容，还经常变。
相对稳定的通用底座是**工作文件夹里的 AGENTS.md 文件**：支持它的工具会自动读取；
其他能读项目文件的 agent 也能按其中的明确路径打开工作流文档。

所以这套工具的核心不是"一个插件"，是"一个自足的工作文件夹"：初始化时把所有工作说明书拷进你的文件夹，AGENTS.md 负责指路（"处理今天的招聘→去读某某文档"）。之后换工具，招聘数据和流程都还在。
为了让常见工具还能自动触发 skill，初始化会从同一份 `skills/` 建立三个项目级入口：
`.agents/skills/`（Codex / Agent Skills）、`.claude/skills/`（Claude Code）和
`.qoder/skills/`（Qoder）。这些入口是链接，不复制内容；没有稳定项目级发现目录的工具继续走
`AGENTS.md`，不靠猜测私有目录。

避开的坑：绑死一家工具，用户换工具就全废。

### 工作流程文档里一个数字都不写

年龄线、学历线、薪资范围，每家公司都不一样。如果通用工具里预置了示例数字，用户就会把别人的标准当成默认值稀里糊涂用下去——这比没有标准更糟。

所以规矩是：**所有具体标准只存在于用户自己的 CONTEXT.md 里**（这个文件就是你的"招聘标准手册"，由梳理环节问出来）。它是这套工具的"唯一事实源"（single source of truth——全项目只认这一处，其他任何文档和它冲突，都以它为准）。流程文档只写"去读手册"，执行时现读。手册还是空的？流程拒绝开工，先把你引去梳理。

避开的坑：标准写在两个地方，改了一处忘了另一处，AI 不知道听谁的。

### 邮箱只是简历入口，不是指令入口

飞书邮箱能省掉“手动查邮件、下附件、再把文件丢给 AI”这段重复操作，但邮件主题、正文、发件人名和附件名都来自外部，不能当成 AI 指令。

所以邮箱流程固定是只读的：只查用户指定的时间窗，先按官方发件域缩小范围，再读邮件。它不标已读、不移动或删除、不回复或转发；风险邮件、压缩包、可执行文件和格式不明附件都不自动下载。通过检查的简历才进原有 review 流程。

避开的坑：为了省一次手动下载，却让 AI 读了无关邮件、执行了邮件里的伪指令，或把同名简历相互覆盖。

### 对内、对外，文件夹层面分开

去哪些公司挖人、什么背景的人要避开、薪资给到多少——这些是你的竞争信息，发错一份麻烦立现。
所以直接在文件夹上分开：对外的 JD 随便发；对内笔记放在单独的 `_internal` 文件夹里，文件第一行就写着"不外发"。日报也有红线：敏感信息不写进去，平台上打码的名字保持打码。

### 搜索词越用越准

搜索关键词这东西，坐在办公室想是想不准的。只有真实命中的简历会告诉你什么词有效。
所以每天收工前有个固定动作：从今天"初筛通过"的简历里，反过来提取出好用的搜索词，记进一张迭代表；明天搜人之前先读这张表。用得越久表越厚，搜得越准。这是整套流程里唯一会"学习"的环节，成本就是几行表格。

## 三、防着 AI 自己偷懒

写这些工作说明书时的基本假设是：执行它的 AI 可能偷懒、跳步、凭印象编造。对策不是叮嘱它"请认真"，而是全部写死在文档里：

- **开工必读三份文件**（标准手册、工作须知、岗位对内笔记），不许凭记忆干活。防它拿自己训练时的"常识"当你的标准。
- **每一步都写清"完成判据"**（completion criterion——什么才算做完的验收标准）。比如寻源这步："每个岗位，两个平台、每个平台两个入口，都要跑过，漏一个就不算做完"；台账这步："今天接触过的每个人在表里有且只有一行，数量对得上"。防它干一半就宣布完成。
- **一天一个新对话，一个岗位一个新对话**。简历原文很快会把 AI 的上下文（context——一次对话能装下的内容总量，相当于它的脑容量）塞满，塞满之后判断会变钝——变钝就先把台账日报存好，开个新对话接着干。核心一句话：**没写进文件的判断等于丢了**。
- **初始化先看后动**。发现文件夹里已经有工作区，就只补缺的文件，绝不覆盖你的台账和标准手册。防重跑一次初始化，把几个月的积累冲掉。
- **踩过的坑直接写进文档**。比如：两个程序同时操作一个浏览器会卡死、猎聘对聊过的人再打招呼会重复发消息……这些都是实际踩出来的，写死在参考文档里。基础差点的 AI 照着做就行，不需要自己会排查。
- **每个可选功能都有"降级路径"**（就是备胎方案：好的用不了，自动换个差一点但能用的）。没装飞书工具？日报存成本地文档，约面试给手动建会清单，简历改为用户本地提供。扫不了码登录？先把文件夹建好，登录记进待办。简历下载失败？标个"未获取"，不许死循环重试。防一个小问题瘫痪整条流程。
- **"能发出去"和"能给人看"是两回事**。日报除了存成文档，还能推一张飞书卡片到手机上。卡片这东西有个陷阱：格式检查工具（校验器）说"合法"，不等于它长得能看——只有标题加几大段文字的卡，机器完全放行，人看了却抓不到重点。所以卡片这步写了两道关：先过机器校验，再过四个自问（三秒能读出结论吗？数字有没有单独成格？状态标签是不是真状态？单段文字是不是一屏能扫完？）。第二道关只能靠自查，写进文档才不会被跳过。

- **安全底线焊死**。"绝不自动点不合适"这条在模板里明确标注"不可删"。防将来某天有人图省事把它当废话删掉。

## 四、方法论从哪来

写这些 skill 文档的手法，大量借鉴了 [mattpocock/skills](https://github.com/mattpocock/skills) 这个仓库（作者是 TypeScript 圈很有名的教学者 Matt Pocock）。他有个说法值得记住：**AI 是个随机系统，skill 文档存在的意义就是从里面拧出确定性——让 AI 每次都走同一个流程**。

从他那里学来的：
- **"什么才算做完"要写清楚**（上一节第一条，出处就是他）；
- **主文档写短，细节放附件**：主说明书只写顺序、判断、安全规则，短到 AI 一定会读完；命令细节和格式沉到参考文档，用到才翻；
- **用有分量的词当锚点**（他叫 leading words）：像"命脉"、"铁律"、"红线"、"台账"这种词，AI 一看就懂分量，一个词顶三句解释；
- **流程画成一条主路加岔路**："初始化（一次）→ 梳理岗位（每岗一次）→ 每日流水线（天天跑），发现标准不对就带着台账数据回去重新梳理"，好过一张平铺的功能列表；
- **别把 AI 的对话拖太长**（上一节第三条）；
- **先查事实，再问取舍**：岗位梳理参考他的 [grilling](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md)（`grill-me` 的当前实现），把前提已确定的问题成批提出，每题附建议；招聘版以形成可执行标准为收口条件。

也学了他的"总目录"skill（router skill）：他有二十多个 skill，做了个 `/ask-matt` 帮用户记；这里的 `ask-viy` 是同一个思路——用户不用记任何流程名，问它就行。只有三个 skill 的时候没做（一张路由表就够），第四个 skill 进来、加上用户全是新手，才补的。

有几样看了但故意没学：
- 他的工具靠 `npx skills add` 一条命令装到全局（装给电脑上所有 AI 工具共用）——我们的核心场景是"文件夹自己带全套"，全局安装只当补充办法；
- 他那套写代码的流程（issue tracker 任务卡管理、TDD 测试驱动开发）——领域不一样，招聘不需要任务卡系统，台账里的一行就是我们的"任务卡"。

## 五、想清楚了不做的

- **不做全自动招聘**：约面试有流程帮你建日程拉面试官，但建之前必经你确认；谈薪、发 offer 则完全不碰，逐案等你发话。工具是副驾驶，方向盘在你手里。
- **不预置任何一家公司的标准**：连示例数字都不给（引导语只说"有的公司设线、有的不设"）。
- **不碰平台的私有接口**：两个工具操作的是你自己登录的浏览器，用你自己的账号和额度，不搞破解。
- **不做独立 ATS 管理系统**：不加数据库或注册登录。纯文本文件仍是事实源，本机进展看板展示工作区任务与候选阶段，不另建候选数据库、不通过网页操作招聘平台。所有 Agent 共用一个网页看板，不再维护独立原生面板与注册入口；共享模型、记录协议和资料／岗位脚本继续保留。工作流先写真实进度，再按宿主能力打开或复用本机网页；缺少打开能力时交付完整本机链接。动态提示来自已落盘的步骤和候选结果，读取连接正常不等于招聘进程仍在运行。
- **页面直接说明对象与事实**：近期进展分开呈现人选、岗位、已核实事件与细节，预约时段和记录更新时间分别表达；全部事项按岗位分组，资料详情逐层返回。新记录使用结构化对象，旧记录只按可靠来源恢复关联，缺失明确提示，不从自由文本猜人岗。岗位“在招”只含明确在招，“我的关注”通过独立面板编辑个人集合；未知状态另有可点击提醒。这些展示与单网页维护决定见 [ADR 0003](adr/0003-web-only-board.md)。
- **待决定事项不随任务结束丢失**：每轮事实和跨轮事项分别记录。用户在聊天里作决定，资料同步和后续执行分别核实；面板保留待确认、暂缓和未落实动作的入口。岗位标准仍以 CONTEXT 为准，事项记录不建立第二套标准，见 [ADR 0001](adr/0001-cross-round-decisions.md)。