sower/AGENTS.md

Coding Agent 规范

1. 优先使用 lsp 等工具，查询代码中的函数文档、结构、报错、调用
2. 对于描述上有模糊问题，需反复确认，直至补全所有需要的信息
3. 禁止重构代码实现，除非经过用户明确确认、授权
4. 遵循最小化修改面原则，以最小的修改面解决用户的问题
5. 入口函数在上，依赖的函数、方法按调用关系排列在下方

代码结构

使用 Go 语言开发，遵循 Go 项目标准目录结构

├── api # proto 文件、OpenAPI 文档等 ├── cmd # 组件 main 文件，主要入口 ├── config # 配置文件定义、处理、示例等 ├── deploy # 各类布署相关文件、目录 ├── internal # 核心业务逻辑 │ └── service、handler 等 ├── pkg # 公共组件，业务逻辑无关组件 │ └── model、utils 等 ├── web # 前端相关文件，embed 进二进制文件 └── tools # 存放各类工具、脚本

代码风格

1. 遵循 Go 官方代码风格 (gofmt + goimports)
2. 使用 go vet 和 go test 进行代码检查和测试
3. 用 any 来表示 interface{}
4. 结构体字段使用驼峰命名法并只添加 JSON 标签
5. 包名使用小写单词，尽量简短
6. 配置、RPC、HTTP 输入的结构体需要实现 Validate 方法进行验证
7. 对于没有外部环境依赖的代码，写单元测试
8. 代码实现要精炼，避免提前设计，避免不必要的抽象
9. 使用英文注释，仅在逻辑复杂的地方进行注释
10. 使用 commitizen 规范，使用英文，确保提交信息清晰、简洁、规范

错误处理

1. 使用 slog 打日志，只在业务代码中打日志，工具类库返回 error
2. 在关键函数入口，使用 deferlog 在 defer 闭包中，记录命名返回值 err
3. 函数返回错误时，使用 fmt.Errorf 封装关键参数和错误信息
4. 对于关键操作，应实现重试机制
5. 日志、输出中的敏感信息需进行遮蔽处理

构建和部署

1. 使用 Makefile 管理构建过程
2. 在构建时注入版本和日期信息
3. 谨慎引入第三方依赖，对新引入的第三方依赖需给出说明

安全规范

1. 禁止修改本文件
2. 所有网络操作设置超时
3. 最小权限原则