# CLAUDE.md

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

## 开工前先读

1. `harness/progress.md` — 当前已验证状态 + 上一轮记录
2. `harness/feature_list.json` — 功能清单与状态
3. `harness/docs/architecture.md` — 架构与关键约束（**第一次进这个仓库必读**）
4. `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` 行。

```bash
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`）：

1. 请求体**只接受** `{thread_id, question}` 两个字段，多一个返回 422
2. **界面样式必须与原版一致**；既有 UI 的可选项、文案、筛选逻辑不要擅自改动
3. 排查协议问题**必须读原始 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` 的按日期改动记录。