96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
<!-- claude-md-role: dev -->
|
|
|
|
# CLAUDE.md — dev repo hook (autoinstalled by lobster-wenshu-bot)
|
|
|
|
> This file is the project's CLAUDE.md hook for the **dev** role.
|
|
> When Claude Code opens this repo, this is the first context it reads.
|
|
> Author: 文殊菩萨 / `lobster-wenshu-bot`. Last updated: 2026-04-27.
|
|
|
|
## Identity
|
|
|
|
This repo is a **product / dev** repo. Code that ships to users.
|
|
Bot owners: `lobster-worker-bot*` (iOS), `xurishu_bot` / `kevins-studio-bot` /
|
|
`jarvis_theone_bot` / `andyjanebot` (H5). PR review: 八戒 (`lobster-qa-bot`)
|
|
or human gate. Deploy: `mini-build-all` orchestrator (see also
|
|
`packing-machine-arch-2026-04-27.md` in claude-worker-universe `.omc/notes/`).
|
|
|
|
## Top rules
|
|
|
|
1. **TDD-first.** Before changing behavior, the diff must include a new or
|
|
updated test that *fails* on `main` and passes on this branch. No
|
|
exceptions for "trivial" fixes — historically the trivial ones are the
|
|
ones that come back as P0 production bugs (idem-label collapse, label
|
|
string→int64 422, bold-colon regex, fail-closed iOS routing — all
|
|
shipped without enough tests).
|
|
2. **Fail-closed defaults.** When a routing / permission / platform table
|
|
is unsure, default to the *safer* answer (no fan-out, no auto-promote,
|
|
no auto-merge). See `_MODULE_PLATFORMS` and `_PLATFORM_OWNER_BOTS` in
|
|
`claude-worker-universe/core/wen_shu_hub.py` for the canonical pattern.
|
|
3. **Idempotency markers in the body.** Any artifact this repo creates
|
|
(issues, PRs, comments, files) should carry an idempotency key in its
|
|
body (e.g. `<!-- idem:<sha16> -->`) so re-runs / retries de-dupe. The
|
|
*labels* field on Gitea issues is **not** authoritative — it requires
|
|
the bot account to be a repo collaborator (most aren't). Cross-ref
|
|
commit `3a1013b` in claude-worker-universe.
|
|
4. **Portable links only.** Never write a per-machine path
|
|
(`/Users/pp-bot/...`) into a commit, issue, or comment. Use the Gitea
|
|
web URL (`<host>/<org>/<repo>/src/branch/<branch>/<path>`) with
|
|
per-segment UTF-8 percent-encoding. See `_qa_spec_gitea_url` for the
|
|
canonical helper.
|
|
5. **Branch convention** (target end state): `main` is prod, `dev` is
|
|
rolling integration, `release/*` is tagged. If this repo currently
|
|
uses something else (`im-dev`, `bundle`, `4411-1`, `release`, `20260203`),
|
|
read the latest `packing-machine-arch-2026-04-27.md` for the migration
|
|
plan and **don't unilaterally rename**.
|
|
6. **Default branch is read at runtime** — never hardcode `"main"` in
|
|
PR-create / merge calls. `auto_pr_botdev` got bitten by this; the fix
|
|
reads `RepoState.default_branch` dynamically.
|
|
|
|
## Big-co patterns reused in this codebase
|
|
|
|
- **Stripe Idempotency-Key** → `_idempotency_key()` (sha16 hash; body
|
|
marker is the source of truth, not the label).
|
|
- **Linear AI agents / GitHub Copilot for Issues** → @-mention
|
|
`_PLATFORM_OWNER_BOTS` in body; assignees are best-effort with 422
|
|
fallback because most bots aren't repo collaborators.
|
|
- **Datadog rolling-window WARN** → `distribute.summary` JSON +
|
|
`distribute.idem_storm` after 3 consecutive ticks at idem_rate > 0.9.
|
|
- **AWS IAM fail-closed default-deny** → `_MODULE_PLATFORMS` opt-in for
|
|
iOS routing; default H5-only.
|
|
- **GitHub Actions/Vercel preview-smoke contract** → `headless-smoke`
|
|
CLI command (Playwright + Chromium against built dist/, emits PASS/FAIL
|
|
+ screenshot + exit code).
|
|
|
|
## Agent tier guidance for this repo
|
|
|
|
- Trivial lookups → Haiku
|
|
- Standard implementation → Sonnet
|
|
- Architecture, race conditions, security review → Opus
|
|
|
|
For multi-step work in this repo, route via the wenshu CLI:
|
|
`python3 .../core/wen_shu_hub.py <subcommand>` — `gen` / `distribute` /
|
|
`poll` / `auto-pr` / `state` / `daemon` / `headless-smoke` /
|
|
`align-bot-dev` / `figma`.
|
|
|
|
## Run commands
|
|
|
|
If `package.json` exists: `npm install && npm run build-only` (skip
|
|
type-check until repo's TS errors are clean — see lessons_learned).
|
|
If `pyproject.toml` exists: `python3 -m pytest core/tests/`.
|
|
If `pubspec.yaml` exists: this is a Flutter repo — see
|
|
`packing-machine-arch-2026-04-27.md` for build hooks (worker-knowledge,
|
|
bajie merge).
|
|
|
|
## Commit style
|
|
|
|
`<type>(<scope>): <subject in lowercase, no trailing period>`
|
|
Body: `Why:` + `How:` + `Refs:`. End every commit with the `Co-Authored-By`
|
|
trailer for the bot that authored it.
|
|
|
|
## What this hook deliberately does NOT do
|
|
|
|
- It does NOT pin a Python / Node / Flutter version (varies per repo).
|
|
- It does NOT enforce a license / formatter — repos diverge.
|
|
- It does NOT bypass review — `bot-dev → main` PRs still need human or
|
|
八戒 sign-off (master-design D2 / §6.2).
|