AI 助手开发协作指南 (AGENTS.md)

本文件定义了 xops-cli 项目的开发流程、质量标准和协作规范。所有 AI 助手（包括当前及未来的会话）在执行任务前必须仔细阅读并严格遵守。

🚀 1. 项目开发规范 (Development Standards)

项目采用 "研究 -> 思考 -> 拆解 -> 执行 -> 验证" 的闭环开发流程。在执行任何代码修改前，必须展现清晰的逻辑链条。

研究与分析：首先确认当前环境状态，使用工具深度分析受影响的代码上下文。
深度思考：在写代码之前，必须先输出具体的修改策略，评估对项目依赖和架构设计的兼容性。
任务拆分：将复杂需求拆解为多个独立、可验证的子任务，逐步推进。
文档同步 (核心红线)：更新代码的同时，必须同步更新相关的文档（如 README.md、CLI 帮助信息、代码注释等）。未更新文档的任务视为未完成。

语言版本：Go 1.26+ (严禁降级)。
命名规范：遵循 Go 社区的缩写命名惯例，ID, URL, SSH, CLI, SFTP, TCP 必须全大写（例如：使用 nodeID，禁止使用 nodeId）。
错误处理：
- 不准静默失败：所有返回 error 的函数必须被检查。
- 显式忽略：若确定无需检查，必须使用 _ = 或 _, _ = 显式标记，禁止直接留空。
- 错误字符串不应以标点符号（如 ! 或 .）或换行符结尾。
变量赋值：避免无效赋值，若变量赋值后不再使用，必须删除或使用下划线忽略。

Commit 规范：提交信息必须遵循以下格式：
- feat: ... (新功能)
- fix: ... (修复)
- chore: ... (配置/维护)
- ci: ... (流水线修改)
- docs: ... (文档更新)
- test: ... (测试用例)
分支与合并：仓库设置了强制 PR 规则，紧急修复 Lint 或 CI 配置文件时，可利用管理员 Bypass 权限直接推送到 master。

强制要求测试 (核心红线)：必须为所有新增功能、核心逻辑或修复的 Bug 编写对应的测试用例（Unit Test 或 Integration Test）。拒绝任何无测试覆盖的代码修改。
强制校验规范：在任何 git push 或提交 PR 之前，必须在本地终端执行并成功通过：
1. go build ./... (确保编译通过)
2. go test ./... (确保逻辑正确且测试通过)
3. golangci-lint run ./... (确保代码质量 0 Issues)
Linter 配置：使用 golangci-lint v2.x。修改 .golangci.yml 后，必须运行 golangci-lint config verify 进行格式检查。
常用命令：
- make build：本地编译二进制文件
- make test：运行所有测试
- golangci-lint run ./...：运行全量代码扫描
- golangci-lint run --fix ./...：自动修复可修正的 Lint 问题
CI/CD：依赖 GitHub Actions 进行 CI/CD，启用 Dependabot 进行依赖自动更新。处理 Dependabot PR 时优先本地 go build 验证。

提示：在任何时候，代码的“干净程度”优于实现的“速度”。