Agent 开发指南

项目入口规则

本文件是 Codex、Claude Code 或其他 coding agent 进入本项目后的第一入口。执行任何开发、修复、重构或检查任务前，必须先阅读本文件。

必读文档

开始任务前，必须先阅读：

docs/04-development-rules.md
docs/05-project-architecture.md
tasks.md

根据任务类型继续阅读：

需求或功能范围：docs/02-prd.md
技术栈或依赖：docs/03-technical-stack.md
UI 布局和交互：docs/07-ui-design.md
图片预览、拖动、缩放、旋转、坐标换算、导出一致性：docs/08-image-editor-design.md
打包发布：docs/09-packaging-release.md
项目愿景和边界：docs/01-product-vision.md

执行方式

默认执行流程：

阅读本文件。
阅读必读文档。
打开 tasks.md。
找到第一个未完成任务。
只完成这一个任务。
不扩大任务范围。
修改前先阅读相关已有代码。
完成后更新 tasks.md 中对应任务状态。
运行必要验证。
创建 Git 提交。
汇报修改内容、验证结果和未完成事项。

如果用户指定了某个任务，以用户指定任务为准，但仍必须阅读相关文档。

任务边界

必须遵守：

每次只做一个明确任务。
不顺手重构无关代码。
不修改与当前任务无关的文件。
不替换技术栈。
不新增未经说明的第三方依赖。
不删除用户素材、输出图片、配置或日志。
不把临时调试代码作为正式代码提交。

如任务需求不清楚：

优先按已有文档保守实现。
若会影响架构、技术栈、数据结构或用户流程，必须先询问用户。

技术约束

必须遵守：

Python 版本：Python 3.7。
GUI 框架：PySide6。
PySide6 版本：PySide6==6.5.3。
图片处理：Pillow。
配置和模板：JSON。
打包：PyInstaller，优先 onedir。
第一阶段目标系统：Windows 10 / Windows 11。

禁止：

禁止切换到 Electron、Web、C#、C++、Tkinter、wxPython 或其他 GUI 技术栈。
禁止将项目改造成前后端分离应用。
禁止依赖公网服务完成核心功能。
禁止使用只支持 Python 3.8 及以上的依赖版本。

代码结构约束

必须遵守 docs/05-project-architecture.md 中的分层：

src/app/：GUI 层。
src/app/widgets/：UI 组件。
src/core/：与 GUI 无关的核心模型、合成和批量逻辑。
src/services/：配置、模板、文件、日志等服务。
tests/：测试。

禁止：

禁止把所有功能写进 src/main.py 或一个窗口类。
禁止让 core/ 依赖 PySide6 UI 控件。
禁止在 UI 按钮事件中直接堆叠大量图片处理代码。
禁止复制两套单张合成和批量合成逻辑。

验证要求

根据任务范围执行验证：

文档修改：检查路径、标题、引用和明显格式问题。
Python 代码修改：运行语法检查。
GUI 修改：尽量启动程序确认窗口可打开。
图片处理修改：验证至少一张衣服图和一张印花图合成结果。
批量处理修改：验证成功、失败和进度反馈路径。
打包修改：验证 PyInstaller 打包产物能启动。

如果无法验证，最终回复必须明确说明未验证项和原因。

Git 要求

完成任务后：

查看 git status。
只提交本任务相关文件。
提交信息使用简洁英文，例如：

feat: implement file scanning service
fix: handle invalid template config
docs: update task plan
chore: add logging setup

如果远端推送失败，需要说明失败原因；本地提交仍应保留。

标准接续提示

当用户要求继续开发时，agent 应按以下方式理解任务：

请先阅读 AGENTS.md、docs/04-development-rules.md、docs/05-project-architecture.md 和 tasks.md。
然后从 tasks.md 中找到第一个未完成任务，只完成这一个任务。
不要扩大范围。
完成后更新 tasks.md，运行必要验证，提交 git，并汇报结果。

4.1 KiB Raw Blame History Unescape Escape