Skip to content

docs: clarify development constraints and error contracts#437

Open
AkashiSensei wants to merge 1 commit into
raids-lab:mainfrom
AkashiSensei:docs/issue-416-dev-constraints
Open

docs: clarify development constraints and error contracts#437
AkashiSensei wants to merge 1 commit into
raids-lab:mainfrom
AkashiSensei:docs/issue-416-dev-constraints

Conversation

@AkashiSensei

Copy link
Copy Markdown
Contributor

Clarify Crater development constraints and error-contract documentation across backend, frontend, CLI, website, and development Skills.

Changes

  • Contributor docs: Refine root, backend, frontend, CLI, and website contribution guidance so development constraints are placed in the right authority documents instead of scattered across thin entrypoints.
  • Backend/API errors: Document bizerr / resputil.HandleError expectations, point contributors to live definition files such as backend/internal/bizerr/groups.go, backend/internal/resputil/handle.go, and backend/internal/resputil/response.go, and keep concrete codes as examples rather than copied tables.
  • Frontend and CLI error presentation: Clarify that clients should preserve actionable backend msg, HTTP status, and business-code facts while allowing frontend/CLI-specific presentation where needed.
  • CLI constraints: Centralize admin namespace, argument validation, backend API support checks, Skill separation, error-context preservation, and common error-scenario recording in cli/docs/SPEC.md, cli/docs/REVIEW.md, CLI Skill templates, and shared CLI Skills.
  • Development Skills: Update crater-devel-* Skills so future Agents route code/docs/review work consistently and prompt developers for the required manual checks.

Testing

AI:

  • git diff --check: passed
  • git commit -s: passed repository pre-commit hook, including Website, Frontend, and Backend checks
  • diff -q between repository crater-devel-* Skills and locally installed ~/.agents/skills/crater-devel-*: matched after local sync
  • Branch check: docs/issue-416-dev-constraints is 1 ahead / 0 behind relative to origin/main

Developer:

  • Manually read all current modifications and confirmed the documentation and Skill changes are ready to submit.

Other

  • This is a documentation and Skill-only change. No frontend UI behavior is changed, so screenshots are not included.

澄清 Crater 后端、前端、CLI、website 与开发 Skills 中的开发约束和错误返回契约。

修改

  • 贡献文档:整理根目录、backend、frontend、CLI 和 website 的贡献说明,确保开发约束沉淀在合适的权威文档中,而不是分散在薄入口里。
  • 后端 / API 错误:说明 bizerr / resputil.HandleError 的使用期望,指向 backend/internal/bizerr/groups.gobackend/internal/resputil/handle.gobackend/internal/resputil/response.go 等实时定义文件,并要求具体 code 只作为示例而不是复制成长表。
  • 前端与 CLI 错误展示:明确客户端应保留后端 msg、HTTP 状态和业务码等排查事实,同时允许前端 / CLI 在需要时做本地化或领域化展示。
  • CLI 约束:将管理员命名空间、参数校验、后端 API 支持检查、Skill 分离、错误 context 保留和常见报错场景沉淀规则集中到 cli/docs/SPEC.mdcli/docs/REVIEW.md、CLI Skill 模板和 shared Skill 中。
  • 开发 Skills:更新 crater-devel-* Skills,让后续 Agent 在代码、文档和 review 任务中按同一套规则路由,并提示开发者完成必要人工检查。

测试

AI:

  • git diff --check:通过
  • git commit -s:通过仓库 pre-commit hook,包括 Website、Frontend 和 Backend checks
  • diff -q 对比仓库内 crater-devel-* Skills 与本地安装的 ~/.agents/skills/crater-devel-*:本地同步后一致
  • 分支检查:docs/issue-416-dev-constraints 相对 origin/main1 ahead / 0 behind

开发者:

  • 人工阅读检查了当前所有修改,并确认这些文档与 Skill 变更可以提交。

其他

  • 本 PR 只修改文档和 Skills,不涉及前端 UI 行为,因此不附截图。

Resolve #416

- refine contributor docs for backend, frontend, CLI, website, and shared development workflow
- document API error contract references, actionable backend messages, and frontend/CLI error presentation expectations
- centralize CLI command, admin namespace, skill separation, and error-context rules in SPEC and related skills

Refs raids-lab#416

Signed-off-by: AkashiSensei <fengzhiyuyi2013@gmail.com>
@AkashiSensei AkashiSensei marked this pull request as ready for review June 22, 2026 14:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Skills 和开发约束问题与改进

1 participant