一、这是什么

我创建了 project-interview 技能，一个通过交互式问答采访，引导用户把项目信息梳理成结构化文档的 AI 助手。

它的工作方式很像一位经验丰富的项目顾问：先自己做功课（看代码、读文档、翻 Git 历史），然后跟你聊几个关键问题，最后输出一份结构完整的 Markdown 项目文档。

🔗 源码与使用说明：https://github.com/isLouisHsu/skills/tree/main/skills/project-interview

与普通的"AI 帮我写文档"不同，它解决的核心问题是**“我不知道该写什么”**。它不是等你给出一堆材料再整理，而是主动引导你——从项目背景到技术决策，从团队分工到踩过的坑，通过层层递进的对话，把你脑子里零散的项目信息一点点"问"出来，再组织成文档。

文档结构根据项目体量自动适配：

  • 小型项目（工具脚本、小模块）：项目概述 + 使用方法 + 技术要点，1-2 页
  • 中型项目（独立应用、服务）：覆盖核心章节，3-5 页
  • 大型项目（平台、系统）：完整章节结构，言之有物即可

章节涵盖：项目概述、背景与动机、目标用户、核心功能、技术方案、团队与分工、项目进展、成果与数据、挑战与经验、后续规划、术语表。

二、为什么需要这个 Skill

写项目文档的痛苦，往往不是"写"这个动作，而是"不知道从哪开始"。

很多人有过这样的经历：老板让整理一份项目文档，你打开编辑器，光标闪了十分钟，只写出一个标题。不是对项目不了解——恰恰相反，你天天做这个项目，太熟悉了，熟悉到不知道哪些信息对别人来说是重要的。

这就是"知识诅咒"： 身在其中的人觉得不言自明的东西，读文档的人完全不了解。你写"基于 PDS 做了优化"，但读者根本不知道 PDS 是什么；你跳过"为什么选 Redis 不选 MySQL"，但这个决策恰恰是后人最想知道的。

Project Interview 要解决的就是这些卡点：

  1. 要整理项目时不知道说什么。 没有文档模板，没有提问清单，面对空白文档大脑也一片空白。Project Interview 内置了完整的话题池，从项目定位到技术决策，从团队分工到经验教训，按节奏逐个引导，你只需要回答即可。

  2. 人工整理容易遗漏细节。 人写文档容易跟着自己的思维惯性走：技术出身的只写架构，产品出身的只写功能，运营出身的只写数据。Project Interview 站在"外人"视角，主动捕捉被忽略的信息——你提到缩写时它会追问全称，你跳过因果链条时它会补问中间环节。

  3. 在初稿上修改比空白开始简单。 一张白纸让人退缩，但看到一份"大概对、需要改"的草稿，人的编辑本能就会被激活。Project Interview 的 workflow 是先做功课出草稿，标记出 [待补充] 的地方，然后邀请你"看看哪些需要补充或纠正"——对话成本远低于从零写作。

  4. 知识诅咒：身在其中，盲区最多。 用户说"大家都知道"或"就是那个"时，Project Interview 会温和地请他展开——文档读者不在"大家"里。它会追问术语全称、补全因果链条、挑战那些"不言自明"的假设，最终文档中专业术语和缩写首次出现时都会加上解释。

  5. 文档结构和篇幅难以把控。 小项目被写成十几章的长篇大论，大项目只有三段话——这两种情况都很常见。Project Interview 先判断项目规模（看文件数、目录结构、Git 活跃度），再决定文档该多长、哪些章节该展开、哪些可以省略。

  6. 非技术项目或没有代码仓库时，AI 无从入手。 很多项目没有代码可分析——市场活动、业务流程梳理、研究报告。Project Interview 支持"纯对话模式"，通过 2-3 轮轻松的问题破冰，自动生成第一版草稿，再进入迭代完善。

三、如何使用

安装技能：

1
npx skills add https://github.com/isLouisHsu/skills --skill project-interview

然后在 AI Agent（如 Claude）中触发：

1
/project-interview 帮我整理这个项目

或者直接说：

  • “帮我写个项目说明”
  • “总结一下这个项目”
  • “我要写项目交接文档”

整个流程只需四步：

第一步：AI 做功课。 如果你在代码仓库里，AI 会自动扫描项目结构、读取 README、查看技术栈配置、翻最近 20 条 Git 记录——1-2 分钟内建立对项目的全局理解。小型项目甚至可以快速浏览所有源码。

第二步：出草稿。 AI 把调研了解到的东西整理成文档，保存到当前目录（{项目名称}_项目文档.md），标记不确定的部分为 [待补充]，然后展示给你。

第三步：对话补充。 你看着草稿说"技术方案这里不对"“背景部分多写一点”“PDS 是我们内部的数据平台”——AI 逐条吸收，每收集 3-4 轮更新一次文档。不确定的地方说"不清楚"或"跳过"，AI 不会纠缠。

第四步：收尾定稿。 清理所有 [待补充] 标记，保存最终版，展示给你确认。后续想调整随时说，AI 直接改文件。

四、它是如何生效的

1. 主动调研：先做作业再开口

Project Interview 的核心原则是能从代码和文档中了解到的信息，不要问用户。

启动后立即行动，不需要征求同意。AI 会：

  • 浏览顶层目录，判断项目规模
  • 读取 README、CHANGELOG、CLAUDE.md 等文档
  • 查看 package.json / pyproject.toml / pom.xml 了解技术栈
  • 看 git log 了解活跃度和近期方向

小型项目可以快速浏览所有源码，大型项目只看核心入口和模块结构——目标是"建立全局理解"，不是"读懂每一行"。

2. 草稿驱动：让编辑本能代替写作焦虑

调研后不是继续追问，而是立即输出一版草稿。

心理学上有个概念叫"空白页恐惧症"（Blank Page Syndrome）——面对空白的编辑器，人的创造力会被抑制。但看到一份有框架、有内容、只是需要修改的文档时，批判性思维和编辑本能会被激活，阻力大幅下降。

草稿中不确定的部分标记为 [待补充：xxx]，让用户一眼看到需要他输入的地方。这种"半成品"策略是 Project Interview 最有效的设计之一。

3. 对话节奏：一次只问 1-2 个问题

很多 AI 助手做信息采集时，喜欢一次性抛出 10 个问题让用户填写——这跟填表没有区别，体验很差。

Project Interview 严格控制节奏：

  • 一次只问 1-2 个问题
  • 用通俗的语言提问，避免专业术语
  • 根据回答灵活追问，不机械走清单
  • 允许用户随时喊停（“差不多了”“先这样”）

对话轻松自然，像跟同事聊天，不像在做问卷调查。

4. 打破知识诅咒：站在外人视角追问

这是 Project Interview 最重要的职责之一。

当用户使用缩写时，它追问全称和含义：“你提到了 PDS，这个具体是指什么？”

当用户跳过因果链条时，它补问中间环节：“从 X 到 Z 中间经历了什么？”

当用户说"大家都知道"时，它温和地请他展开：“文档读者不在’大家’里，能具体说说吗？”

最终文档中，所有专业术语和缩写首次出现时都加上解释或全称——这是人工整理时最容易遗漏的细节。

5. 篇幅适配：让文档匹配项目体量

一个 100 行的小工具不需要 12 个章节的长文档，一个大型平台也不该只有三段话。

Project Interview 根据项目规模自动调整：

项目规模 判断依据 文档篇幅
小型 十几个文件，单目录 1-2 页，3-4 个章节
中型 多模块，有配置文件 3-5 页，核心章节全覆盖
大型 多层级目录，多服务 完整章节，言之有物

6. 纯对话模式：没有代码也能用

很多项目没有代码仓库——市场活动、业务流程、研究报告。这时候 Project Interview 切换到纯对话模式：

  1. 先问最轻松的问题：“你的项目叫什么名字？大概是做什么的？”
  2. 根据回答判断项目类型，后续提问自动适配
  3. 2-3 轮对话后生成第一版草稿，进入正常的"草稿→补充"流程

这种场景下，每个问题都必须有价值，Project Interview 会确保不问废话。

五、总结

Project Interview 解决的不是"写文档"的技术问题，而是"不知道写什么"的心理障碍。

它通过三个关键设计降低阻力：

  1. AI 先做功课——不是从零开始问，而是带着理解来对话；
  2. 先出草稿再修改——激活编辑本能，绕过空白页恐惧；
  3. 站在外人视角追问——打破知识诅咒，捕捉被忽略的盲区。

这套机制适合以下场景：

  • 项目交接：离职或转岗前，把脑子里的事落到文档里；
  • 项目复盘：阶段性总结，梳理成果、挑战和经验；
  • 对外汇报：给老板、客户、投资人写项目说明；
  • 个人整理：项目做久了，借文档梳理重新理解全局；
  • 非技术项目：没有代码，纯靠对话也能产出结构化文档。

Project Interview 把"写项目文档"这个让人望而生畏的大任务，拆解成了"回答几个问题、修改一份草稿"的小步骤——而这往往是让人动起来的关键。

六、Q&A

1. 这跟直接让 AI "帮我写个项目文档"有什么区别？

直接让 AI 写文档，通常有两种模式，都有明显缺陷：

模式 问题
你给材料，AI 整理 你得先写出/找出一堆材料，这本身就是最累的环节
AI 直接生成通用模板 内容空洞，跟你的项目无关，改起来比重写还累

Project Interview 走的是第三条路：AI 主动调研 + 对话引导 + 迭代完善。

  • 有代码时，AI 先读取项目信息，出带内容的草稿；
  • 没代码时，AI 用 2-3 个问题破冰，出基于你描述的草稿；
  • 然后进入"你指出问题 → AI 修改 → 再看再改"的循环。

你不是从零写，也不是改一份空洞模板——你是在一份"大概对"的初稿上精修。

2. 它会问很多问题吗？我很忙，不想花太多时间。

不会。设计原则就是"轻量级"：

  • AI 能从代码里读到的，绝不问你；
  • 一次只问 1-2 个问题，不是问卷调查；
  • 你说"不清楚"或"跳过"，它不纠缠；
  • 你说"差不多了"，它立即收尾。

根据实际使用反馈，一个中型项目通常 10-15 分钟对话即可完成核心文档——比你自己从零写要快得多。

3. 文档结构是固定的吗？我想调整章节顺序或增减内容。

结构是参考性的，不是强制的。

AI 会根据项目类型和规模自动选择合适的章节组合，但你可以随时说：

  • “把技术方案放到前面”
  • “加一个部署相关的章节”
  • “去掉团队分工这部分”

AI 会立即调整文档结构并重新组织内容。

4. 纯技术项目用 project-interview，和用 project-docs-manager 有什么区别？

Project Docs Manager Skill：让 AI 自主驱动项目迭代的文档引擎

这两个 skill 解决的是不同层面的问题：

维度 Project Interview Project Docs Manager
核心目标 把项目信息从人脑子里"问"出来，生成文档 建立持续迭代的项目记忆系统，让 AI 自主驱动
使用时机 一次性或低频：项目交接、阶段性总结、对外汇报 持续使用：每次迭代都更新，形成动态知识库
输入来源 代码 + 对话（用户回答） 代码 + 文档 + 执行结果 + 人工反馈
输出形态 一份结构化的项目文档 分层的文档体系（索引 + 详情），持续演进
AI 角色 采访者 + 整理者 自主驱动者，基于文档主动提案和执行

简单说：

  • Project Interview 是"项目写真"——在特定时间点，把项目全貌拍下来，输出一份给人读的文档；
  • Project Docs Manager 是"项目大脑"——持续运转，让 AI 继承记忆、自主迭代。

两者可以结合使用：用 Project Interview 快速产出项目的初始文档，然后纳入 Project Docs Manager 的文档体系，成为后续迭代的基线。

5. 生成的文档可以导出到其他地方吗？

生成的文档是标准 Markdown 格式，保存在当前工作目录，你可以：

  • 直接复制到 Notion、语雀、Confluence 等平台；
  • 提交到 Git 仓库作为项目文档；
  • 转换为 PDF 或 Word 格式分享；
  • 作为 Project Docs Manager 的初始 OVERVIEW.md 使用。

文档是你的，AI 只是帮你组织和写出来。