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

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

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

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

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

## 🎨 2. 编码规范 (Coding Standards)

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

## 📦 3. Git 规范 (Git Standards)

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

## 🛠️ 4. 测试、构建与 CI (Testing, Building & CI)

- **强制要求测试 (核心红线)**：**必须**为所有新增功能、核心逻辑或修复的 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` 验证。

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