From 2551f1d5b3bff8c32ce79b12a30ab1bbb7d50be4 Mon Sep 17 00:00:00 2001 From: lobster-wenshu-bot Date: Mon, 27 Apr 2026 13:34:52 +0900 Subject: [PATCH] =?UTF-8?q?docs(claude-hook):=20install=20dev=20role=20hoo?= =?UTF-8?q?k=20(CLAUDE.md)=20=E2=80=94=20=E6=96=87=E6=AE=8A=20batch=202026?= =?UTF-8?q?-04-27?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4bfd110 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,95 @@ + + +# 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. ``) 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 (`///src/branch//`) 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 ` — `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 + +`(): ` +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).