CLAUDE.md

本仓库用 harness/ 管理长时开发。这个文件只做入口，细节都在 harness/ 里。

开工前先读

harness/progress.md — 当前已验证状态 + 上一轮记录
harness/feature_list.json — 功能清单与状态
harness/docs/architecture.md — 架构与关键约束（第一次进这个仓库必读）
harness/sops/session-start.md — 开工流程（含 init.sh 与结构校验两条命令）

规则（必须遵守）

同一时间只做一个功能（feature_list.json 里只有一个 in_progress）
没有可运行证据（构建/测试的实际输出）时，不要声称完成
每次改动完成后立刻更新记录，不要攒到会话结束 —— 攒到最后必然漏记、且已写下的描述会过期（真实发生过）
每次改动完成后立即提交并推送（见下方"提交约定"）
计划类文件只能写进 harness/docs/exec-plans/active/ —— 写到仓库外（如工具自带的 ~/.claude/plans/）或项目根目录都算没写：换个会话接手的人看不到，等于计划不存在。工具生成的草稿在收尾前必须落进仓库。
收尾时跑 node harness/tools/validate-harness.mjs（退出码非 0 就先修）
不要通过重写功能清单来隐藏未完成的工作
不要为了让状态好看而删除或削弱验证步骤
仓库内文件是唯一事实来源 —— 不要把结论只留在聊天里

提交约定

每次改动完成就提交，并推送到 origin —— 不要攒成一个大提交，也不要留给用户手动提交。

提交前的最低要求：

npm run build 通过
已按上面的规则更新 harness/progress.md 与 harness/feature_list.json

提交信息写清「改了什么、为什么」，用中文；结尾带 Co-Authored-By 行。

git add -A && git commit -m "..." && git push origin main

harness/、CLAUDE.md、agents.md 是入库的（2026-09-17 起）—— 参考资料的原则是「计划、质量、技术债和代码一起版本化」，团队 clone 应当能看到。所以记录类改动也要一起提交，别只提交 src/。

仍然不入库的只有带凭据的本机文件：.env.*.local、.claude/settings.local.json，以及 esbuild 生成的 harness/tools/_*.mjs（构建产物，会与源码漂移）。

完成门槛

验证成功、且结果记录进 harness/feature_list.json 的 evidence 与 harness/progress.md 之后，功能状态才能切 passing。

收尾前

按 harness/sops/session-end.md 过一遍清单，当场更新：

harness/progress.md（追加 session 记录）
harness/feature_list.json（状态与证据）
仍损坏 / 未验证的内容

项目速览

青浦区营商智能助手前端（Vue 3 + TypeScript + Vite）。对话走接口 POST /api/chat，前端经适配层翻译成内容标记，渲染层不感知协议。

最容易踩的三条（详见 harness/docs/architecture.md）：

请求体只接受 {thread_id, question} 两个字段，多一个返回 422
界面样式必须与原版一致；既有 UI 的可选项、文案、筛选逻辑不要擅自改动
排查协议问题必须读原始 SSE 载荷，不要只看封装的中间事件

详细索引

想了解	看
架构、目录、核心系统、约束	`harness/docs/architecture.md`
接口契约与字段释义	`harness/docs/reference/`（先读该目录 README）
已知技术债与未决问题	`harness/docs/exec-plans/tech-debt-tracker.md`
质量现状与缺口	`harness/docs/quality.md`
验证流程	`harness/sops/verification.md`
临时脚本放哪	`harness/tools/`

harness/ 与 harness/docs/ 按 .gitignore 约定不入库，缺失属正常。入库的改动记录见 README.md。

CLAUDE.md 3.8 KB History Raw