Project Interview Docs（项目文档与面试材料）

中文 | English

你接手了一个项目，打开仓库，README.md 写着"一个高性能的微服务系统"——没架构图、没 API 列表、没数据模型。两周后你才上手代码。再过两周面试官让你"讲讲这个项目"，你又卡了 30 秒。

这是两个连着的问题：没有文档，和讲不出来。

project-interview-docs 一个 skill 解决两步：

1. 先整理文档 —— 读代码，写出完整的开发文档（架构、模块、API、数据模型、配置、部署），每条都来自 agent 真正打开过的文件
2. 再准备面试 —— 基于上一步的文档，提炼成 30 秒 / 3 分钟 / 10 分钟的口语面试故事

两步同源——面试材料是从文档里提炼的，不是另读一遍代码。所以文档和面试故事永远不会打架：不会出现文档说用 RabbitMQ、面试却说用 Kafka 的矛盾。

两个阶段，一个 skill

阶段	做什么	默认？	逻辑
Phase 1：项目文档	读代码 → 写全开发文档（含细节）	✅ 默认	加法，写全
Phase 2：面试材料	从文档提炼 → 30s/3min/10min + 决策 + 权衡	用户明确要才触发	减法，讲清

你说"整理文档"——只跑 Phase 1。你说"准备面试"——先跑 Phase 1（如果还没有文档），再跑 Phase 2。

它产出什么

Phase 1 产出两层文档，同时给两种人看：

层	给谁看	内容
主叙述	技术决策者、PM	问题、架构、边界、依赖、一条主流程、关键决策
参考细节	接手代码的开发者	公开 API、数据模型、关键配置、构建与部署（含类名、签名、schema）

Phase 2 产出同一条主流程的三个口语版本 + 可选的题库、模拟面试、答案评审。

想看完整产出长什么样？见 references/example-narrative.md——一个支付对账服务从文档到面试材料的完整示例。

为什么不一样

大多数文档工具看一眼 package.json 就生成"本项目用了 Express 和 MongoDB"——一个名词都没对上真实文件。大多数项目总结则变成技术清单，面试官听完不知道你为什么用、付出了什么代价。

这个 skill 的纪律是 read-then-write（读了才写）：

• 仓库里有的代码功能，必须全部写进文档——读到的功能不留漏、不挑拣
• 每个架构名词都能追溯到 agent 打开过的某个文件
• 每个 API、字段、配置项都是真从代码里读出来的
• 代码和 README 说法打架时，代码为准，冲突写进"漂移与缺口"段
• 没证据的数字用占位符 XX 标出，逼你填真数据，绝不臆造补全

怎么用

这是一个 AI-agent skill，遵循 Agent Skills 规范。把整个目录复制进你 agent 的 skill 目录：

<你的仓库>/.agents/skills/project-interview-docs/
# 或个人使用
~/.agents/skills/project-interview-docs/

然后告诉你的 agent：

用 project-interview-docs 读这个仓库，先整理出完整的项目文档。

文档出来后，再说：

基于这份文档，准备面试材料。

完整的两阶段流程、检查顺序、漂移规则在 SKILL.md。

它不做什么

不写 API 参考生成、不写入职手册、不逐文件解释代码。不把整个文件粘贴进去当"文档"。不读不到的代码就编——没定位到的内容用占位符标出，交给你核实。也不臆造性能数字、用户量、或"我主导了 xxx"。

许可证

MIT，见 LICENSE。