project-guide

---
name: project-guide
description: 中文项目导学与项目面经技能：基于本地项目仓库、项目描述或技术材料，生成 导学-{简称}.md 与 面经-{简称}.md，并整理可交接给 /great-resume 和 /interview 的事实摘要；当用户输入“/project-guide”、要求项目导学、项目分析、项目复盘、源码阅读路径、项目面经或 STAR 题库时使用。
---

# /project-guide：项目导学 + 项目面经

基于用户提供的项目仓库、项目描述、技术栈和求职方向，把真实项目整理成两份可落盘的 Markdown：`导学-{简称}.md` 和 `面经-{简称}.md`。本技能关注“项目如何学、如何讲、如何被追问”，不替用户编造公司、职位、数据、上线结果或个人职责。

## 路由边界

- 需要从项目仓库或项目材料生成学习路径、源码阅读顺序、项目亮点、项目面经成稿：使用 `/project-guide`。
- 只需要把经历改成简历 bullet、岗位定位或 HR 开场白：使用 `/great-resume`。
- 已经有简历，需要模拟面试、预测问题或逐轮追问掌握度：使用 `/interview`。
- 需要生成可编辑 HTML/PDF 简历：使用 `/make-resume`；未指定模板时默认使用 ASu 模板，也可以在请求中指定其他模板。
- 需要寻找开源贡献候选、准备 diff 或提交 PR：使用 `/contributor`。

## 输入契约

优先从当前工作区读取项目事实，再结合用户材料。缺少关键信息时最多追问 3 个高信号问题；用户要求先出初稿时，允许用 `待补` 标注缺口。

| 字段 | 必须 | 说明 |
| --- | --- | --- |
| 项目描述 | 是 | 背景、目标、职责、难点、结果；越具体越好 |
| 简称 | 强烈建议 | 用于文件名 `导学-{简称}.md`、`面经-{简称}.md` |
| 技术栈 | 否 | 语言、框架、中间件、观测、发布方式 |
| 求职方向 | 否 | 前端、后端、AI、数据、产品或交叉方向 |

项目材料不足时，优先追问：

1. 你在项目中的个人职责和协作边界是什么？
2. 项目最能展开的技术难点是什么，解决前后的现象如何验证？
3. 是否有指标、日志、PR、截图、上线记录或用户反馈可以作为证据？

可选脚本：

```bash
python3 scripts/project_guide.py check --file description.txt --tech "React, TypeScript" --role "前端"
python3 scripts/project_guide.py build-prompt --short-name "智能BI" --description "..." --tech "..." --role "..."
```

## 简历 bullet 约束

生成 `面经-{简称}.md` 前，先对照 [领域中立 Bullet few-shot](references/examples/bullet-few-shots.md)。few-shot 只用于学习表达结构，不得复制其中的项目名、数字、领域名词或指标。

简历 bullet 必须先抽取 4-6 个架构支柱，再成稿。每条一级 bullet 必须以 `**通用支柱名：**` 开头，随后写清：

- 问题或演进：为什么原形态不够好。
- 机制：采用了什么通用工程机制，以及它如何工作。
- 约束或边界：超时、并发、幂等、降级、观测、扩展点等。
- 结果：可验证的架构变化或真实指标；没有证据时写测量计划，不编造数字。

支柱名必须是外部面试官能理解的架构或工程能力，例如分层容错、可扩展编排、请求可靠性治理。项目实现名不能直接充当支柱名；`RunManager`、`Stream Bridge`、`execution id` 这类实现名应改写为通用表达，或下沉到源码证据索引。

删除“提升性能 / 提高稳定性 / 优化体验”等不可验证结果；私有函数、路径、内部枚举和业务黑话只进入源码证据索引。

## 硬性交付

必须在用户指定的目标项目根目录，或当前打开的工作区根目录，写入两个文件：

| 文件 | 内容 |
| --- | --- |
| `导学-{简称}.md` | 项目学习路径、源码阅读顺序、核心原理、设计决策和验证建议 |
| `面经-{简称}.md` | 简历可用摘要、面试题、第一人称 STAR 口播、追问和源码证据索引 |

`{简称}` 使用用户给定值；未给时从项目名称或描述中提炼 2-8 个字。不得包含 `/ \ : * ? " < > |` 等路径非法字符。

如果当前环境无法写入文件，在对话中输出两个独立 Markdown 代码块，并标明目标文件名。

## 导学文件结构

`导学-{简称}.md` 按以下顺序输出：

1. 前置知识（面试高频标注）
   - 表格列：知识点 / 为何需要 / 在本项目中的位置 / 高频度。
2. 重点亮点与学习顺序（先看这个）
   - 3-6 条。
   - 表格列：亮点标题 / 为什么重要 / 通用技术关键词 / 先看哪些文件 / 建议学习顺序。
   - 亮点标题优先使用通用工程表达，例如状态建模、异步编排、缓存一致性、性能治理、容错降级、观测与定位。
3. 必备知识点
   - 精简 checklist。
4. 推荐阅读（结合仓库）
   - 表格列：主题 / 通用技术点 / 建议阅读位置 / 预计时间 / 读完能回答什么。
   - 每条建议阅读位置必须写项目相对路径；未知时写 `仓库未提供路径，待补`。
5. 自学提醒
   - 固定包含：若某文件或原理看不懂，请继续追问 AI；本技能负责给学习路径与题目，不提供逐行讲解。
6. 项目技术定位
   - 前端 / 后端 / AI / 数据 / 产品 / 交叉 + 一句依据。
7. 核心原理解析
   - 3-6 条，使用“问题 -> 机制 -> 在本项目中的落点”。
8. 关键设计决策
   - 备选 / 取舍 / 风险 / 验证。
9. 量化与验证（含待测，建议）
   - 用建议语气说明怎么测；暂无数据时写 `待测`。

## 面经文件结构

`面经-{简称}.md` 按以下顺序输出：

1. 项目简介（简历可用，1-2 句）
   - 说清“做什么 + 关键技术/形态 + 关键能力”。
   - 不堆叠内部私名。
2. 简历 bullet（4-6 条）
   - 每条一级 bullet 必须以 `**通用支柱名：**` 开头。
   - 先交代问题或演进与个人职责，再写机制、约束或边界、结果。
   - 每条只表达一个支柱，至少包含“问题或演进 + 机制 + 结果”。
   - 没有可靠数据时写定性架构结果或测量计划，不编造百分比、用户量、延迟或排名。
3. 面试问题（15-25 个主问题）
   - 主问题按频率从高到低组织。
   - 可按 3-6 个主题分组，每个主题至少 1 个主问和 2 个追问。
   - 15-25 只统计主问题，追问不计入。
   - 每个主问和追问都必须包含第一人称口播版，且不少于 150 个汉字。
   - 口播应覆盖 STAR：情境、任务、行动、结果。
   - 叙述顺序建议为：场景现象 -> 归因 -> 动作 -> 结果或兜底。
4. 源码证据索引
   - 表格列：主题 / 关键路径与内部符号 / 对应正文位置。
   - 具体文件名、函数名、私有字段、打点名和内部容器名集中放在这里。

## 内部名词约束

面经读者默认是外部面试官。正文应以通用工程语言为主，不把团队黑话直接堆给面试官。

以下内容在面经正文中要主动抽象：

- 私有框架、私有组件、自研 hook、内部 API。
- 项目内部函数名和工具函数名。
- 后端下划线字段、私有枚举、内部状态码。
- 打点事件名、动态配置键、灰度开关键。
- 端内容器私名、私有 JSBridge namespace。
- 3-5 字中文业务代号或团队内部俗称。

翻译方式：

- 私有 hook/action -> store 的 read hook / write action。
- 分层函数 -> 一级路由决策 / 二级视图状态机。
- 后端字段 -> 语义化业务含义。
- 打点事件 -> 某类生命周期或结果指标打点。
- 灰度开关 -> 配置中心下发的 feature toggle。
- 业务代号 -> 某活动、某子产品、某业务流程。

预算：

- 主问口播中黑名单内部名词最多 2 次，且每次必须紧跟通用抽象说明。
- 追问口播中黑名单内部名词最多 1 次。
- 违反预算时重写该题。

## 与 ASu 工作流交接

生成两个文件后，在最终回复中附两段交接摘要：

### 交给 /great-resume 的项目事实摘要

包括：

- 项目名称和目标岗位。
- 个人职责边界。
- 关键技术动作。
- 可核验证据。
- 可写入简历的候选表述。
- 待补指标或待确认事实。

### 交给 /interview 的高风险 Claim 清单

包括：

- Ownership Claim：主导、负责、Owner、0 到 1 等强表述。
- Metric Claim：百分比、延迟、用户数、准确率、覆盖率等指标。
- Architecture Claim：架构设计、核心链路、调度、状态机、缓存、容错等。
- Result Claim：上线、采用、效率提升、成本下降等结果。

## 质量门禁

落盘前逐项自检：

- 已生成 `导学-{简称}.md` 与 `面经-{简称}.md`，或已输出等价双文件内容。
- 导学包含重点亮点、学习顺序、推荐阅读和相对路径。
- 导学包含固定自学提醒。
- 面经项目简介可直接放入简历，不堆叠内部私名。
- 面经每条一级 bullet 以 `**通用支柱名：**` 开头，支柱名不是私有类名、函数名、路径、事件名或业务黑话。
- 面经每条一级 bullet 只表达一个支柱，至少具备“问题或演进 + 机制 + 结果”。
- 面经主问题数量为 15-25。
- 主问和追问口播均不少于 150 个汉字。
- 面经包含源码证据索引。
- 没有把团队成果冒领为个人成果。
- 没有编造指标、上线结果、公司、职位或技术栈。