docs: AGENTS.md 添加项目目录规范章节

新增第14节:项目目录规范
- 目录结构速查表
- 禁止在根目录放置的文件类型
- 新增目录检查清单
- 文件命名规范

配合 docs/PROJECT_STRUCTURE.md 使用
This commit is contained in:
2026-04-07 19:01:49 +08:00
parent 6b2b450e91
commit 2ae146a0b9

View File

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