base-ai

Imported from luohuatingyu/base-ai (AGENTS.md). Install upstream with npx skills add luohuatingyu/base-ai. Copyright stays with the author.

AGENTS.md

General Rules

• Python 必须使用 3.12 版本。
• 禁止执行 git push 操作，除非用户明确要求。
• 每一次修改文件后必须执行 git commit 提交，commit message 使用英文简洁说明变更内容。
• 调试时保存的调试文件需告知用户保存位置，调试完成后必须清除。
• 功能开发必须遵循以下流程：
  1. 需求理解：梳理功能目标、使用场景、验收标准、涉及范围及明确不包含的内容；存在歧义时必须先向用户确认。
  2. 影响分析：检查相关代码、配置、数据结构、接口和测试，识别兼容性、安全性及潜在风险。
  3. 制定方案：给出具体实施步骤、涉及文件、技术设计、测试用例清单、潜在风险及回滚方式。
  4. 方案确认：方案必须经用户人工确认通过后才允许修改代码；测试范围也必须一并确认；若方案未通过，则根据用户反馈调整方案并重新确认。
  5. 代码与测试设计：设计实现逻辑，并为每项验收标准建立对应的测试用例；根据实际适用范围规划正常、边界、异常、权限安全、兼容性和回归测试。
  6. 功能实现：仅修改已确认范围内的文件，遵循项目规范，不得夹带无关改动或临时调试代码。
  7. 测试验证：运行相关测试和构建命令；若测试用例未全部通过，则返回代码与测试设计阶段，分析失败原因并完善设计与实现；不得通过删除、跳过或弱化有效测试规避失败；交付时必须列出实际执行的测试命令、通过和失败结果，以及未执行的测试。
  8. 变更检查与提交：检查 git status 和 git diff，确认只包含当前任务相关变更；清理调试文件后按规范提交。
  9. 功能交付：向用户说明功能整体行为、关键实现、使用的技术栈、测试结果、影响范围、已知限制及提交信息。
• 实现过程中若发现需要重大调整方案，或涉及新增依赖、配置修改、数据迁移、删除文件等重要变更，必须暂停操作并重新取得用户确认。
• 若因环境或外部依赖无法完成测试，不得直接判定功能完成；必须明确说明未验证内容、受阻原因和建议的验证方式。

测试用例要求

• 每一项验收标准必须至少对应一个可执行测试用例，并在方案中建立“验收标准—测试用例”映射。
• 修改业务逻辑时，必须根据实际适用范围覆盖以下场景：
  1. 正常场景：主要业务流程和典型输入。
  2. 边界场景：空值、最小值、最大值、临界值、空集合和超长输入。
  3. 异常场景：非法参数、依赖失败、资源不存在、状态冲突和超时。
  4. 权限与安全场景：未登录、无权限、越权访问、敏感数据泄漏和恶意输入。
  5. 兼容性场景：已有接口、数据格式和默认行为不发生非预期变化。
  6. 回归场景：本次修改可能影响的历史功能。
• 修复缺陷时，原则上必须先添加能够稳定复现缺陷的失败测试，再修复代码并确认测试通过。
• 新增或修改分支逻辑时，必须覆盖新增分支；不得仅测试正常路径。
• 对多个同类输入场景，优先使用参数化测试，避免重复测试代码。
• 测试必须验证业务结果和关键副作用，不得只验证接口调用成功或状态码。
• Mock 仅用于隔离外部依赖，不得通过过度 Mock 绕过核心业务逻辑。
• 除非用户明确同意，不得删除、跳过、弱化已有有效测试，也不得仅为提高覆盖率编写无业务断言的测试。
• 测试数量不设固定下限，以验收标准和风险场景完整覆盖为准。
• 测试用例清单至少说明测试层级、前置条件、输入、预期结果、对应验收标准及覆盖的场景类型。

Agent Mode Rules

• 禁止修改第三方代码，第三方代码会在 README 中标注。
• 编写的代码方法层级必须补充中文注释，核心代码注释完整。
• 不要修改与当前任务无关的文件。
• 重要变更，如删除文件、修改配置，执行前先询问确认。
• 不要引入未使用的依赖。
• 优先编辑现有文件，避免新建不必要的文件。
• 任务结束前必须检查工作区，确保本次任务产生的文件均已按要求提交或清理，不得遗留未保存或未跟踪文件。
• 除非用户明确要求，禁止将新增的 Markdown 文件纳入 Git 跟踪；可临时创建，但不得提交，并必须在任务完成后清理。
• 遵循项目现有代码风格和命名规范。
• 代码变更后必须执行 docker compose up --build -d 重新构建并启动服务，确保代码变更已应用到运行环境。
• 执行 docker compose up --build -d 过程中若因端口被占用而失败，必须停止占用该端口的容器后重新执行命令。
• docker compose up -d --build 仅用于统一重新编译和启动环境，不能替代测试执行；不得单独执行后端 mvnw compile 或前端 npm run build 作为重新编译方式。
• 修改代码后必须执行与变更直接相关的测试套件；项目存在完整测试套件时，相关测试通过后还应执行完整测试，除非已说明耗时或环境限制。
• 业务代码变更后必须自动执行覆盖测试并更新 TEST_REPORT.md，详见"测试报告管理规则"章节。
• 测试过程、结果、问题及覆盖范围等相关记录必须统一写入 TEST_REPORT.md，不得使用其他文件记录。
• 若项目未提供可执行的测试命令，必须明确说明，并提供建议的验证方式；不得仅凭编译成功判定功能完成。
• 临时测试代码、调试验证代码不得提交到仓库。
• 测试完成后必须移除本次测试临时创建的测试相关文件；项目已有及为验证功能而保留的正式测试用例除外。
• 提交前检查 git status 和 git diff，只提交相关文件。

测试报告管理规则

测试报告基准点

• 项目根目录的 TEST_REPORT.md 包含当前的测试基准点（Git Commit Hash）。
• 测试基准点标记了测试报告验收的代码版本，作为判断是否需要重新测试的依据。

重新测试触发条件

必须重新运行测试并更新TEST_REPORT.md的情况：

• ✅ 修改了业务代码（backend/src/main/java/ 下的非测试代码）
• ✅ 修改了Domain实体类
• ✅ 修改了Repository接口
• ✅ 修改了Service业务逻辑
• ✅ 修改了Controller接口
• ✅ 修改了核心配置（影响业务逻辑的配置）

无需重新测试的情况：

• ❌ 仅修改配置文件（不影响业务逻辑）
• ❌ 仅修改文档（README.md、注释、AGENTS.md等）
• ❌ 仅修改前端代码（frontend/ 目录）
• ❌ 仅修改数据库脚本（database/ 目录）
• ❌ 仅添加或修改测试代码（backend/src/test/ 目录）
• ❌ 仅修改构建配置（pom.xml、Dockerfile等，不影响业务逻辑时）

测试报告更新流程

1. 检查基准点：

   • 读取 TEST_REPORT.md 中的 Git Commit Hash
   • 使用 git diff <baseline-commit> HEAD -- backend/src/main/java/ 检查业务代码是否变更

2. 判断是否需要重测：

   • 如果上述 git diff 有输出，说明业务代码已变更，需要重新测试
   • 如果用户明确要求重新测试，也应执行

3. 执行测试：

   • 运行完整的测试套件：mvn test 或 mvn clean test
   • 记录测试结果（通过数、失败数、错误数、跳过数）
   • 记录关键模块的测试结果（如Domain层、Service层等）

4. 更新TEST_REPORT.md：

   • 更新测试执行结果
   • 更新Git基准点为当前最新的commit
   • 更新测试日期
   • 如果有新的发现或问题，更新相关章节

5. 提交变更：

   • 提交业务代码变更
   • 单独提交 TEST_REPORT.md 的更新，commit message说明测试覆盖的变更范围

测试报告内容要求

TEST_REPORT.md 必须包含以下信息：

• 📋 Git基准点：Commit Hash、提交信息、测试日期、分支
• 📊 测试执行结果：总用例数、通过率、失败原因分析
• 🎯 测试覆盖范围：明确说明测试覆盖了哪些模块和功能
• 🔄 重测触发条件：清晰定义何时需要重新测试
• ⚠️ 已知问题：记录当前测试中发现的问题和限制
• 📝 下次测试建议：针对未覆盖或需要改进的测试场景

示例检查命令

# 检查自上次测试以来业务代码是否变更
BASELINE=$(grep "Commit:" TEST_REPORT.md | head -1 | awk '{print $2}')
git diff $BASELINE HEAD -- backend/src/main/java/

# 如果有输出，说明需要重新测试
if [ -n "$(git diff $BASELINE HEAD -- backend/src/main/java/)" ]; then
    echo "业务代码已变更，需要重新运行测试"
fi

自动覆盖测试规则

每次业务代码变更后必须自动执行以下流程：

1. 检测代码变更：

   BASELINE=$(grep "Commit:" TEST_REPORT.md | head -1 | awk '{print $2}')
   CHANGED=$(git diff $BASELINE HEAD -- backend/src/main/java/)

2. 如果检测到业务代码变更，自动执行：

   • ✅ 重新构建服务：docker compose up --build -d
   • ✅ 运行完整测试套件：cd backend && mvn test -B（或使用 Docker 容器运行）
   • ✅ 记录测试结果（总数、通过、失败、错误、跳过）
   • ✅ 分析测试失败原因
   • ✅ 更新 TEST_REPORT.md：
     • 更新测试执行结果
     • 更新Git基准点为当前HEAD
     • 更新测试日期
     • 记录新发现的问题或改进
   • ✅ 提交测试报告：git add TEST_REPORT.md && git commit -m "Update test report for <feature>"

3. 测试失败处理：

   • 如果测试失败，必须在 TEST_REPORT.md 中记录：
     • 失败的测试用例
     • 失败原因分析
     • 是否为已知问题
     • 修复计划或说明
   • 不允许在测试失败的情况下完成功能开发
   • 如果是合理的测试失败（如测试本身需要更新），必须更新测试用例

4. 执行时机：

   • 功能开发完成后
   • 准备提交代码前
   • 发现测试基准点与当前代码差异较大时

5. 测试报告更新模板：

   ### 本次变更测试结果（YYYY-MM-DD）
   
   **变更范围**：[简述本次业务代码变更]
   
   **测试执行结果**：
   - 总测试用例：X个
   - 通过：X个 (XX.X%)
   - 失败：X个
   - 错误：X个
   - 跳过：X个
   
   **关键模块测试**：
   - Domain层：X/X (通过率)
   - Service层：X/X (通过率)
   - Repository层：X/X (通过率)
   - Controller层：X/X (通过率)
   
   **新发现的问题**：
   - [如有，列出问题]
   
   **Git基准点**：[新的commit hash]

注意事项

• 自动覆盖测试是强制性的，不可跳过
• 测试必须在业务代码提交前完成
• 测试报告更新应该作为单独的commit
• 如果测试基准点距离当前代码较远（如跨越多个功能开发），必须重新执行完整测试
• 测试失败时不得强行提交代码，必须修复后才能继续

Plan Mode Rules

• 非编码内容尽量使用中文。
• 制定方案前先充分理解需求，明确涉及的文件和范围。
• 方案需包含具体实施步骤，评估潜在风险。