study-tool
106818cfc2
现象：AGENTS.md 里 5 处规则互相打架——逐次询问 vs 认领/提交/升版本；不构建 vs 前端必须 build；全部提交 vs 禁 add -A；每次提交 bump 版本号，而实际 24 次提交版本仍是 0.0.8。 docs/agent_board.md 没有 Agent 列，认领规则无法落地；docs/agent_workflow.md 是 0 字节； docs/todo.md 与 docs/progress/todo.md 双账本漂移，旧文件还写 platforms/gdgxk.py。 根因：规则按「想防的事」逐条追加，没有回头消解冲突；项目契约和 Agent 行为混在同一个入口文件里。 边界： - AGENTS.md 只留行为规则；日志 / 目录 / 插件契约指向 docs/architecture.md（两节内容已并入，未丢失） - 版本号改为只在发版提交时 bump，普通提交不动 - 看板改四列表头，状态带时间戳「进行中 (MM-DD HH:mm)」，超 24h 可接管 - 删除 docs/todo.md；其中 2 条仍未修的代码问题已迁入 docs/progress/todo.md，待办按 待做 / 已知偏差 / 未验证 重排 - 不改代码、不改版本号、不打 tag 运行了什么：git status 自查（只提交这 6 个文档文件，uv.lock 是原有改动未提交）；提交时 pre-commit 跑 ruff / web typecheck / commitizen 没跑什么：没跑测试、没构建、没跑 pnpm build（本次无代码改动）
5.9 KiB
5.9 KiB
AGENTS.md
本文档用于约束本项目中的 AI / 自动化开发行为。
优先级：用户当前消息 > 本文件 > 其他文档。 与本文件冲突时以用户消息为准，并在收尾时问一句要不要同步改本文件。
基本原则
- 先读现有代码，再动手修改，优先沿用项目已有结构和写法。
- 写代码保持最少行数，能简单实现就不要引入复杂抽象。
- 标准格式、协议、解析、压缩、加密、日期等通用能力优先使用成熟稳定的库，不要手写底层实现，除非用户明确要求或项目已有实现必须沿用。
- 不要为了“兼容更多场景”写大量分支，只实现当前明确需要的功能。
- 项目尚未上线，不需要兼容旧数据；表结构或字段调整时直接按新设计修改，不写旧字段兼容、数据迁移兜底或删除旧表的清理逻辑，除非用户明确要求。
- 不要改无关文件，不要顺手重构；顺手发现的 bug 不修，记进
docs/progress/todo.md并注明位置。 - 如果工作区已有用户改动，不要回滚，不要覆盖；只在必要范围内追加修改。
动文件之前（Plan-first）
- 修改已存在文件前，先给一次改动清单：路径 / 改什么 / 为什么 / 影响面；同意后本次任务内连续执行，不逐文件问。
- 新建文件、新建目录不用逐次问，但要列进清单。
- 删除、覆盖、格式化、
git reset --hard、git checkout .、git push -f、删分支 / 删 worktree，必须单独列出、单独同意。 - 用户当条消息里点名的改动，视为已同意。
验证口径
- 产物生成必须做：前端改动 →
cd web && pnpm build，static/一起提交，不直接改static/里的产物。 - 质量验证不做：不跑测试、不跑全量 lint / typecheck，由用户执行。例外：用户明确要求、发版、或改到核心逻辑（认证 / 计费 / 写库 / 定时任务 / 并发 / 对外协议）。
- 提交时 pre-commit 会跑
ruff-check/ruff-format/web typecheck，失败就修；这不算“检查语法”。 - 结论必须带依据：命令、
文件:行、报错原文；没核实就写「未核实」。 - 命令失败、文件读不到、解析失败 → 结论是「未知」，不是「空」或「没问题」。
- 没跑的验证写
Not tried: <原因>。
多 Agent 协作
-
看板表头统一为
| 路径 | 任务 | Agent | 状态 |，历史行Agent列留空。 -
开工前在
docs/agent_board.md追加一行，状态写进行中 (MM-DD HH:mm)（如进行中 (11-01 19:40)）。同一路径已有别人的进行中→ 停下问，不硬改。 -
完成后只改自己那行：状态改
已完成,待实测，保留行（它是完成记录）。不动别人 Agent 的行。 -
超过 24 小时仍是
进行中的行（按状态里的时间算）视为过期，可以接管，但要注明接管人。 -
只有一个 Agent 在顺序开发时，认领行可以省，但改前必须先看有没有人动过同一文件。
-
并行开发（≥2 个任务同时改代码） 时，每个任务用独立 worktree：
git worktree add ../study-tool-<任务名> -b <任务名> cp .env ../study-tool-<任务名>/ uv sync pnpm --dir web install合并回 master 后
git worktree remove ../study-tool-<任务名>。单人顺序开发不强制建 worktree。 -
禁止
git add -A/git add .：必须按具体文件名暂存，防止误提交其他 Agent 未完成的改动。
反复提醒沉淀
- 同一个坑出现 ≥2 次（或同一个注意事项被用户纠正 2 次以上）才写成规则；只出现 1 次的先记
docs/agent_workflow.md的「观察中」。 docs/agent_workflow.md每条格式：规则 / 为什么 / 证据（提交 sha、报错原文、文件:行）/ Seen N×。- Seen ≥3 且用户同意，才升级进本文件；写入前先全文搜重，有同义条目就改旧的，不新增重复条目。
- 补充时写成明确、可执行的规则，避免只写模糊描述。
- Agent 只提议并附证据，不自己改本文件。
文档规范
- README 保持简洁，只放项目介绍、核心功能、快速开始和文档入口。
- 后续待办写到
docs/progress/todo.md，分三段：待做 / 已知偏差 / 未验证。 - 已实现但还需要用户测试确认的事项写到
OPTIMIZATION.md。 - 每次任务完成前，根据实际变更检查并更新
OPTIMIZATION.md与docs/progress/todo.md；没有变化也要确认无需修改。 - 文档里的命令、路径、字段名必须与代码一致；引用代码写
路径 + 符号名，不写行号。 - 文档不要写过期日期；除非用户明确要求记录具体时间。
发版本流程
- 发版本时，先把
CHANGELOG.md的Unreleased变更整理成新的版本记录，并保留空的Unreleased标题。 - 只在发版提交时提升版本号：
metadata.yaml的version与pyproject.toml的version一起改（bumpversion）；普通提交不动版本号。 - 提交范围：只提交本次任务的文件（
git add <具体路径>）。提交前git status必须只剩本次任务的文件；出现别人的或无关的改动 → 停下问，不顺手提交。 - 提交完成后，给当前提交打最新版本号对应的 tag（如
v0.0.8）。打之前git tag -l查重、git rev-parse HEAD确认，不覆盖已有 tag。 - 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需
pnpm build并把static/一起提交。 - 完成一个能独立回滚的改动就提交一次（一个 commit 一个目标）。提交信息：标题
<区域>: <用户可见的变化>；body 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。
项目契约
- 日志约定、目录分层、平台插件契约统一维护在
docs/architecture.md，改动结构时同步更新；本文件不再重复这些内容。