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

提交约定

提交时机由用户决定（用户 2026-09-24 指示：「后续不要再自动提交和推送了，只有我要求你做你才做」）—— 这条取代了原先「每次改动完成就提交并推送」的约定：

改完代码：照常跑构建/验证、更新 harness/progress.md 与 harness/feature_list.json （记录仍要写，它是仓库的事实来源），但不要 git add/commit/push
变更留在工作区，收尾时说明「改动未提交」，等用户说「提交」或「提交并推送」再执行
用户的一次「提交」指示只对那一轮生效；之后回到默认（不提交）
用户明确要求提交时，按原要求执行：npm run build 通过 + 记录已更新，提交信息写清「改了什么、为什么」（中文），结尾带 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/、CLAUDE.md、agents.md 自 2026-09-17 起入库（见上方「提交约定」）。团队 clone 即可看到状态、计划与技术债；改动流水另见 README.md 的按日期改动记录。

CLAUDE.md 4.6 KB Lịch sử Raw