93 lines
3.8 KiB
Markdown
93 lines
3.8 KiB
Markdown
# 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]
|
||
```
|