Imported from csdiyfree/project-interrogator (AGENTS.md). Install upstream with npx skills add csdiyfree/project-interrogator. Copyright stays with the author.

AGENTS.md — 项目拷打器

供 Codex / Claude Code 在本仓库工作时遵循。

项目是什么

项目拷打器:面向 CS 求职者与保研学生的 AI 面试模拟器,核心是针对简历中每个项目做「逐项深度追问 + 实时面试官手稿 + 具体改进指南」。

• 产品与模块原始设计:ideas/
• 架构与开发权威文档:develop_prompt/v01/
  • 00_架构设计总览.md — 总纲
  • 01_接口契约.md — 前后端唯一契约(API / SSE / 数据模型),改动前后端任一端前先看它
  • 02_产品提示词附录.md — 所有中文 LLM 提示词全文
  • agents/ — 8 份并行开发提示词(BE0-3 后端、FE0-3 前端)
• 代码:backend/(Python/FastAPI)、frontend/(React/TS/Vite)——两目录独立开发、独立启动。

工程铁律(不可违背)

1. 最短实现,严禁过度设计:逻辑本质是「拼提示词→调 LLM→拆结果」,不加用不到的抽象/容错/中间件。
2. 前后端彻底分离:只通过 01_接口契约.md 交互;前端用 mock 层可脱离后端独立开发。
3. 提示词中文、集中管理:后端 backend/app/prompts/*.md + 注册表;不在代码里临时拼提示词。
4. 界面零提示性文字:让设计说话,风格「优雅的温暖科技人文」。

密钥与安全

• 真实密钥只放在 backend/.env(已被 .gitignore 忽略),仓库内只有 backend/.env.example 占位符。
• 严禁把任何密钥写进被跟踪的文件(含文档、代码、commit message)。
• 提交前必须 git status 确认 .env 等敏感文件不在暂存区。

Git 提交规则

何时提交:仅在用户明确要求时创建提交;不擅自提交,不擅自 git push。

提交信息格式(Conventional Commits,主题用简洁中文):

<type>(<scope>): <主题，≤50 字，无句号>

<可选正文：解释“为什么”，每行 ≤72 字>

• type:feat(新功能)/ fix(修复)/ docs(文档)/ refactor(重构)/ style(样式格式)/ test(测试)/ chore(杂项/构建)。
• scope:用 agent/模块编号或区域 —— be0 be1 be2 be3 fe0 fe1 fe2 fe3 backend frontend docs infra。
• 主题用祈使、聚焦一件事;正文说清动机与权衡,而非罗列改了什么。

提交纪律:

• 一个提交只做一件逻辑变更;不要把后端与前端无关改动混在一个提交(infra/跨端契约变更除外)。
• 按文件名精确 git add <files>,不要无脑 git add -A/.(防止误提交 .env、大文件)。
• 推送规则:只要本地创建了 commit,就立即推送到远端当前上游分支;若同时创建 tag,也必须同步推送。
• 优先新建提交,不要 --amend 已提交内容;不跳过 hooks(--no-verify)。
• 破坏性操作(reset --hard、push --force、删分支等)须先确认。
• AI 辅助的提交在信息末尾追加:Co-Authored-By: Claude <noreply@anthropic.com>。

示例:

feat(be2): 实现拷问 SSE 流式接口与分段解析

按契约 §5 把模型的 [手稿]/[结束]/[问题] 分段输出
转为 manuscript_delta/question_delta/closing_delta 事件,
结束时落库并触发指南生成。

并行开发约定

• 启动顺序:先并行 BE0 与 FE0(地基),完成后各自并行铺开 BE1/2/3 与 FE1/2/3。
• 后端就绪后,前端把 VITE_USE_MOCK 置 false 联调。
• 任何一端要改契约,先改 01_接口契约.md 并同步另一端。