diff --git a/AGENTS.md b/AGENTS.md index 3cbd8b0..91d4298 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -234,3 +234,47 @@ - 每次解决的问题必须记录解决方案。 - 每次踩过的坑必须记录避免方法。 - 每次验证通过的命令必须记录执行结果。 + +## 14. 项目目录规范 + +### 14.1 目录结构 + +详见 `docs/PROJECT_STRUCTURE.md`,核心规范: + +| 目录 | 用途 | 注意事项 | +|------|------|----------| +| `bin/` | 编译产物(二进制) | 禁止提交 | +| `cmd/` | 应用入口 | 每个应用一个子目录 | +| `internal/` | 私有内部包 | 不可被外部导入 | +| `pkg/` | 公共外部包 | 仅当需要作为独立库发布时使用 | +| `scripts/` | 脚本 | 按 dev/deploy/ops/test 分类 | +| `tools/` | 工具脚本 | Python/Shell 工具 | +| `configs/` | 配置文件 | JSON/YAML/TOML | +| `deployment/` | 部署配置 | Docker/K8s/Compose | +| `docs/` | 项目文档 | 分类管理 | +| `data/` | 运行时数据 | SQLite数据库等 | +| `logs/` | 日志输出 | | +| `uploads/` | 用户上传 | | + +### 14.2 禁止在根目录放置 + +- ❌ 编译产物(*.exe, *.dll → bin/) +- ❌ 临时测试输出(*_result.txt, *_test.txt → 删除) +- ❌ 运行时日志(*.log → logs/) +- ❌ 环境配置文件(.env → 不提交) + +### 14.3 新增目录检查 + +添加新目录前,确认: +1. 是否有必要?能用现有目录表达吗? +2. 符合命名规范?小写字母、中划线分隔 +3. 放置位置正确?对应到规范中的位置 +4. 是否需要版本控制?data/logs/uploads 通常不提交 + +### 14.4 文件命名规范 + +- Go源文件:`snake_case.go` +- 测试文件:`*_test.go` +- 配置文件:`snake_case.json/yaml/toml` +- 脚本文件:`snake_case.sh/ps1/py` +- Markdown:`kebab-case.md` 或 `snake_case.md`