2026Technology-Competition/AGENTS.md

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]