# 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`

## 执行方式

默认执行流程：

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

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

## 任务边界

必须遵守：

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

如任务需求不清楚：

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

## 技术约束

必须遵守：

- 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`。
- 只提交本任务相关文件。
- 提交信息使用简洁英文，例如：

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

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

## 标准接续提示

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

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