# AGENTS.md — AI 协作方式与项目说明

## 项目说明

**指摘管理系统（IMS）**：基于 AI Agent 驱动的质量问题全生命周期管理系统（项目性质：新规）。
- 后端：Java 17 + Spring Boot 3.5（Maven 多模块：ims-common / ims-api / ims-service / ims-web）
- 前端：React 19 + TypeScript + Vite + Ant Design 6
- AI 引擎：Ollama（本地，默认）+ DeepSeek API（备选），Spring AI 抽象接入
- 数据：PostgreSQL 16 + pgvector、Redis 7、MinIO；数据库经 Docker（WSL2）运行
- 核心：Agent 感知-规划-行动-记忆闭环，8 个工具，写操作人工审批，SSE 实时流

## AI 协作方式

本仓库全程采用 **"需求分析 → AI生成方案 → 人工审核 → AI编码 → 测试验证 → Bug修复 → 代码清理 → 提交部署"** 开发范式（详见 DESIGN.md §2 范式流程图），AI 与人工的职责边界：

| 环节 | AI 职责 | 人工职责 |
|------|---------|---------|
| 需求分析 | 梳理需求、提出方案 | 确认需求与验收标准 |
| 方案设计 | 生成技术方案、架构设计 | 评审把关 |
| 编码 | 按方案实现代码 | 确认技术选型、审查结果 |
| 测试 | 编写测试、定位修复缺陷 | 执行验证 |
| 部署 | 构建、提交 | 发布与验收 |

使用中文回答问题。

## 日志规则（自动执行）

每次创建或修改代码文件后，在项目根目录的 `_AI_USAGE_LOG.md` 中追加一条记录，必须包含以下字段：日期时间、范式步骤、修改摘要、涉及文件、使用模型

**说明**：

- AI自动填充"日期时间""修改摘要""涉及文件"和"使用模型"，若AI无法获取当前使用模型，可以手动加上。
- "范式步骤"列根据实际情况写，与 DESIGN.md 范式图步骤名称保持一致（如：需求分析、AI生成方案、人工审核、AI编码、测试验证、Bug修复、代码清理、提交部署）。

## 1. 在编码前三思

**别妄下定论。不要掩饰困惑。表面权衡。**

在实施之前：

- 明确表达你的假设。如果不确定，可以问。
- 如果存在多种解读，就提出来——不要默默选择。
- 如果有更简单的方法，请说明。必要时反驳。
- 如果有什么不清楚的地方，就停止。说出什么让人困惑。问吧。

## 2. 简洁优先

**只需解决问题的最低限度代码。不要做任何推测性的。**

- 除了被要求的部分，没有其他特征。
- 一次性代码不做抽象。
- 没有没有“灵活性”或“可配置性”，这是他们主动要求的。
- 不可能的情景没有错误处理。
- 如果你写了200行，可能只有50行，那就重写。

问问自己：“高级工程师会说这太复杂了吗？”如果是，那就简化。

## 3. 手术变更

**只触碰你必须触碰的部分。只收拾你自己的烂摊子。**

编辑现有代码时：

- 不要“改进”相邻的代码、注释或格式。
- 不要重构那些没有坏掉的东西。
- 即使你会用不同的方式，也要匹配现有的风格。
- 如果你发现了无关的死代码，要提一提——不要删除。

当你的更改产生孤儿时：

- 移除那些是你自己改动导致没用到的导入/变量/函数。
- 除非被要求，不要删除已有的死代码。

测试：每一行更改的线条都应直接追踪到用户的请求。

## 4. 目标驱动执行

**定义成功标准。循环直到确认。**

将任务转化为可验证的目标：

- “添加验证”→“为无效输入写测试，然后让它们通过”
- “修复bug”→“写一个复现它的测试，然后让它通过”。
- “重构X”→“确保测试在前后通过”

对于多步骤任务，请提出简要计划：

```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```