القائمة
Use when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | debugging-guide |
| description | Use when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach |
| trigger | debug, error, fail, crash, panic, fix, wrong |
遇到问题时，按以下顺序排查：
go build ./...
常见原因：
_ blank import# 详细输出
go test -v ./internal/engine/
# 单个测试
go test -v -run TestAgentLoop ./internal/engine/
# 带 race detector
go test -race ./...
查看完整 goroutine stack：
go run ./cmd/harness9 2>&1 | head -100
nil pointer panic 通常来自：
make(map[K]V) 初始化）LLM 不调用工具： 检查工具的 Definition() 描述是否清晰，JSON Schema 是否正确。
工具执行失败： 查看 ToolResult.IsError 和 Output 字段，错误信息会回传给 LLM。
无限循环： 检查 WithMaxTurns 配置，默认 50 Turn。
在 internal/context/builder.go 的 Build() 方法末尾临时添加：
fmt.Fprintf(os.Stderr, "=== SYSTEM PROMPT ===\n%s\n===================\n", prompt)
在 registry.Execute 前打印可用工具列表：
for _, def := range registry.GetAvailableTools() {
fmt.Fprintf(os.Stderr, "tool: %s\n", def.Name)
}
如需查看实际 API 请求，在 internal/provider/openai.go 中打印消息列表。
症状：400 Bad Request 或 invalid_request_error
原因：Anthropic Messages API 禁止连续 assistant 消息。
修复：检查 contextHistory 的消息顺序，确保 system→user→assistant→user→assistant 交替。
症状：工具返回 路径超出工作区范围 或类似错误
原因：路径包含 ../ 或绝对路径指向启动目录之外。
修复：Agent 应使用相对于启动目录的路径，如 internal/engine/agent_loop.go 而非 /absolute/path/...。
症状：Agent 不知道有 Skills 可用
检查：
skills/ 目录是否在项目根目录（启动目录）下SKILL.md 文件SKILL.md 是否包含 name 和 description frontmatter 字段[skills] warn 输出正确的目录结构示例：
skills/
├── go-coding-standards/
│ └── SKILL.md ← 必须是这个文件名
└── debugging-guide/
└── SKILL.md
| Warning | 含义 | 修复 |
|---|---|---|
printf 格式不匹配 | %s 传入了非 string 类型 | 修正格式或类型 |
unreachable code | return 后有代码 | 删除死代码 |
loop variable captured | goroutine 捕获了循环变量 | 传参而非捕获 |
Feature auto-development — clarify requirements, generate spec, dispatch dev sub-agent to implement and merge into current branch
Use when the user invokes /commit or asks to commit changes, after a code review has been completed and the changes are confirmed ready to stage and commit to git.
Use when the user invokes /cr, requests a code review, or before committing to verify correctness, security, and quality of new or modified code in the working tree.
Use when the user invokes /pr or asks to push changes and open a pull request, after commits are ready to be pushed to a remote branch and merged into the main branch.
发布 harness9 CLI 新版本。接受可选的 version 参数；若未提供，则自动将当前最新 tag 的 patch 号加 1。执行：切换到 master、拉取最新代码、创建 tag、推送 tag 触发 GoReleaser，并基于两个 tag 之间的提交生成详细、结构化的 Release Note 覆盖 GitHub Release 默认说明。
Use when asked about harness9 architecture, module design, or how components interact — explains the system design