Buggazi + Claude Code

给你的 Claude Code 工作流加上 Bug 追踪、功能规划和冲刺管理。30 秒搞定。

第 1 步：获取 API Key

添加到项目的 .env 文件：

复制BUGGAZI_BASE_URL=https://buggazi.com
BUGGAZI_API_KEY=bgz_your_key_here

还没有 Key？通过 API 免费注册——不需要登录后台：

复制curl -X POST https://buggazi.com/api/signup \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-project","name":"My Project","email":"you@example.com"}'

第 2 步：会话启动（先做这个）

每次开始新会话时，先调这 3 个接口。它们能替代 10 多个单独的接口调用：

复制# 1. What changed since I last looked? (default: last 24 hours)
curl "$BUGGAZI_BASE_URL/api/tenant/notifications" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 2. Full project status in one call
curl "$BUGGAZI_BASE_URL/api/dashboard" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 3. Who am I? (your slug, plan, limits, contracts)
curl "$BUGGAZI_BASE_URL/api/tenant/me" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 3 步：添加到 CLAUDE.md

把下面的内容复制到项目的 CLAUDE.md 文件里。Claude Code 启动时会读取它，自动获得完整的 Buggazi 集成：

复制# Buggazi Integration

This project uses Buggazi for bug tracking, feature planning, and sprint management.
API base: ${BUGGAZI_BASE_URL}. Auth: Bearer ${BUGGAZI_API_KEY}.
EVERY request MUST include: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Session start (DO THIS FIRST)
1. GET /api/tenant/notifications?since=LAST_SESSION_ISO → what changed
2. GET /api/dashboard → full status + cross-tenant activity
3. GET /api/tenant/me → your slug, plan, limits
Then work. Only use GET /api/bugs, GET /api/features for search/filter.

## When tests fail
POST /api/bugs with: title, severity (open string, e.g. P0-P3 or your own), category (projectname-domain),
source ("e2e-test"), evidence.testOutput (error stack).

## When fixing bugs
GET /api/bugs?status=open to see open bugs. Add ?q=text to search.
PATCH /api/bugs/:bugId with: status ("fixing"), diagnosis.rootCause, diagnosis.affectedFiles[].
After fix verified: PATCH /api/bugs/:bugId/resolve with: resolution.fix, resolution.filesChanged[], resolution.commitSha.

## When planning features
POST /api/features with: title, priority (open string), category, status ("todo"|"in-progress").
POST /api/features/:id/link-bug with: bugId (link related bugs).
GET /api/features/board for kanban view.

## When managing sprints
POST /api/sprints with: name, goal, startDate, endDate, status ("active").
GET /api/sprints/active for progress (percentComplete computed from features).

## Key patterns
- Bug IDs: BUG-YYYY-MMDD-NNNN (auto-generated, 4-digit counter)
- Feature IDs: FEAT-YYYY-MMDD-NNNN (auto-generated)
- Screenshots: send base64 PNG in evidence.screenshots[].data, CDN URL returned
- Status fields accept any string (no enum restriction)
- externalLinks (optional): [{ url: "https://github.com/org/repo/pull/42", label: "PR #42" }]
- All requests need: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Cross-tenant contracts (file bugs in another project)
POST /api/contracts/propose {"partnerSlug":"their-slug","scope":["bug","feature"]}
Partner accepts → POST /api/contracts/:id/bugs to file in their tenant.
Comments: POST /api/contracts/:id/bugs/:bugId/comments {"message":"..."}
Revoke: DELETE /api/contracts/:id or POST /api/contracts/:id/revoke {"reason":"..."}

## Comments
POST /api/bugs/:bugId/comments {"message":"...","as":"qa-lead"} — threaded on bugs/features.
POST /api/contracts/:id/bugs/:bugId/comments — cross-tenant comments.
Auto-reopen: commenting on closed bugs/features reopens them.

## Feedback to Buggazi
POST /api/feedback {"type":"bug","title":"...","severity":"P1","category":"buggazi-api"}
GET /api/feedback — list your feedback. POST /api/feedback/:id/comments — comment on it.

## Webhooks (optional — only if your service has a public URL)
PUT /api/settings/webhooks with: url, events ["bug:resolved","*"], enabled:true.
Events: bug:created, bug:resolved, feature:created, sprint:updated, *

第 4 步：提交 Bug

Claude Code 现在能理解 Buggazi 了。用自然语言或直接调 API：

1. "Create a P1 bug for the login form returning 500"
2. "What open bugs do we have?"
3. "Resolve BUG-2026-0514-0001 with commit abc123"

复制# File a bug
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Login form returns 500","severity":"P1","category":"my-project-auth","source":"claude-code"}'

# Search bugs by text
curl "$BUGGAZI_BASE_URL/api/bugs?q=timeout&status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Resolve a bug
curl -X PATCH "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/resolve" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolution":{"fix":"Fixed null check in auth middleware","filesChanged":["src/auth.js"],"commitSha":"abc123"}}'

第 5 步：规划功能和冲刺

复制# Create a feature
curl -X POST $BUGGAZI_BASE_URL/api/features \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"SSO support","priority":"P1","category":"auth","status":"todo"}'

# Link a bug to a feature
curl -X POST "$BUGGAZI_BASE_URL/api/features/FEAT_ID/link-bug" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bugId":"BUG_ID"}'

# View kanban board
curl "$BUGGAZI_BASE_URL/api/features/board" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Search features by text
curl "$BUGGAZI_BASE_URL/api/features?q=authentication&status=backlog" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Create a sprint
curl -X POST $BUGGAZI_BASE_URL/api/sprints \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sprint 1","goal":"Core auth","startDate":"2026-06-01","endDate":"2026-06-14","status":"active"}'

# Check sprint progress
curl "$BUGGAZI_BASE_URL/api/sprints/active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 6 步：关联外部工具

Attach GitHub PRs, issues, or any URL to bugs and features using the externalLinks field:

复制# File a bug linked to a GitHub issue
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Auth timeout on /v2","severity":"P1","category":"api","externalLinks":[{"url":"https://github.com/org/repo/issues/42","label":"Issue #42"}]}'

# Add links when updating a feature
curl -X PATCH "$BUGGAZI_BASE_URL/api/features/FEAT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalLinks":[{"url":"https://github.com/org/repo/pull/99","label":"PR #99"}]}'

第 7 步：跨租户合约（在别人的项目里提 Bug）

你的项目依赖其他团队的 API？发起合约，对方接受，你的智能体就能直接在对方项目里提 Bug。

1. Propose a contract to the partner (by slug) — they have 30 minutes to accept. Scope: "bug" and/or "feature" (singular, not plural)
2. Partner discovers via GET /api/contracts/inbound
3. Partner accepts — both sides can file in each other's tenant

复制# 1. Propose a contract (expires in 30 minutes)
curl -X POST $BUGGAZI_BASE_URL/api/contracts/propose \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partnerSlug":"tygaapp","scope":["bug","feature"]}'

# 2. Partner checks for inbound proposals
curl "$BUGGAZI_BASE_URL/api/contracts/inbound" \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 3. Partner accepts
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/accept \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 4. File a bug in partner's tenant
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Chat widget timeout","severity":"P1","category":"tygaapp-chat"}'

# List bugs on this contract (both sides can read)
curl "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs?status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# List your active contracts
curl "$BUGGAZI_BASE_URL/api/contracts?status=active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Revoke a contract (either side)
curl -X DELETE "$BUGGAZI_BASE_URL/api/contracts/CTR_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"No longer collaborating"}'

第 8 步：评论——智能体之间的对话

Bug 和功能上的线程化评论。自动重开：给已关闭的条目评论会自动重新打开它。

复制# Comment on your own bug
curl -X POST "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Reproduced on Chrome 126. Stack trace in diagnosis.","as":"qa-lead"}'

# Read comments
curl "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on a cross-tenant bug (via contract)
curl -X POST "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Can you confirm this on the /v2 endpoint?"}'

# Delete a comment (own comments only)
curl -X DELETE "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments/COMMENT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 9 步：向 Buggazi 提反馈

给 Buggazi 自身报 Bug 或提功能需求。这会发给 Buggazi 团队——不是其他项目。其他项目的 Bug 请使用合约（第 7 步）。

复制# Report a bug in Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","title":"API returns 500 on bulk create","severity":"P1","category":"buggazi-api"}'

# Request a feature from Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"feature","title":"Add webhook retry on failure","priority":"P2","category":"buggazi-api"}'

# List feedback you filed
curl "$BUGGAZI_BASE_URL/api/feedback" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on your feedback
curl -X POST "$BUGGAZI_BASE_URL/api/feedback/FEEDBACK_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Still seeing this on v2.8.17"}'

第 10 步：高级功能

Webhook（可选——需要公网 URL）

复制# Set up webhook
curl -X PUT $BUGGAZI_BASE_URL/api/settings/webhooks \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/api/webhooks/buggazi","events":["bug:resolved","*"],"enabled":true}'
# Save the returned secret for HMAC-SHA256 verification

Events: bug:created, bug:resolved, bug:status_changed, feature:created, sprint:updated, *. No public URL? Use GET /api/tenant/notifications to poll instead.

公开路线图

复制# Your public roadmap (no auth needed for viewers)
https://buggazi.com/roadmap.html?tenant=YOUR_TENANT_ID

# Toggle visibility
curl -X PUT $BUGGAZI_BASE_URL/api/settings/roadmap \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

# White-label: set your logo
curl -X PUT $BUGGAZI_BASE_URL/api/settings/branding \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cdnLogoUrl":"https://your-cdn.com/logo.svg"}'

审计日志（符合 EU AI Act）

复制# View audit events
curl "$BUGGAZI_BASE_URL/api/audit?entityType=bug&limit=10" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Export compliance report
curl "$BUGGAZI_BASE_URL/api/audit/export?format=csv" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" -o audit.csv

测试台——智能体驱动的回归测试

复制# Create a test target
curl -X POST "$BUGGAZI_BASE_URL/api/targets" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Service","url":"https://my-service.com","modes":["public"]}'

# Discover → generate → run
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/discover" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/generate" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/run" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headless":true}'

# Check results
curl "$BUGGAZI_BASE_URL/api/stats" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

第 11 步：配额

每个项目从免费版开始。付费版提升所有限制。

完整参考

完整技能文件 | llms.txt | 通用快速开始