68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
<!-- agents-md-role: dev -->
|
|
|
|
# AGENTS.md — dev role
|
|
|
|
> Open-standard agent contract per [agents.md](https://agents.md).
|
|
> Companion to `CLAUDE.md` (Claude-specific) — this file works for any
|
|
> AI coding agent (Cursor, Aider, Codex, OpenHands, etc.).
|
|
|
|
## Dev environment tips
|
|
|
|
- Default branch convention: `main` = prod, `dev` = rolling integration,
|
|
`release/*` = release candidates, `feat/*` = ephemeral feature branches.
|
|
If this repo currently uses something else (`im-dev`, `bundle`,
|
|
`4411-1`, `release`, `20260203`), see
|
|
`dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md` for the
|
|
migration plan.
|
|
- For Vue 3 + Vite repos: `npm run build-only` (not `npm run build`)
|
|
to bypass legacy `tsc` errors that block clean builds.
|
|
- For Flutter repos: `flutter pub get && flutter test` before any change.
|
|
- For Swift repos: `xcodebuild -workspace ... -scheme ... test` from the
|
|
workspace root.
|
|
|
|
## Testing instructions
|
|
|
|
- TDD-first. Diff that changes behavior MUST add or update a test that
|
|
fails on the parent commit and passes on this branch.
|
|
- Find existing tests by language:
|
|
- `tests/`, `core/tests/`, `__tests__/` (Python / JS)
|
|
- `test/`, `integration_test/` (Flutter / Dart)
|
|
- `*Tests/` (Swift)
|
|
- Run with the lightest scope that proves the change:
|
|
`pytest core/tests/test_<module>.py` / `vitest run <pattern>` /
|
|
`flutter test test/<file>` / `xcodebuild test -only-testing:<TestClass>`.
|
|
- Pre-existing failures unrelated to your change are NOT in scope to fix
|
|
unless explicitly requested. Note them in your PR body.
|
|
|
|
## PR instructions
|
|
|
|
- Title: `<type>(<scope>): <subject>` lowercase, no trailing period.
|
|
- Body: `Why:` + `How:` + `Refs:` + `Co-Authored-By:` trailer.
|
|
- Default branch is read at runtime — never hardcode `"main"` in
|
|
PR-create / merge calls. See `wen_shu_hub.auto_pr_botdev` for the
|
|
canonical pattern.
|
|
- Idempotency: any artifact (issue, PR, comment) the agent creates MUST
|
|
carry an idempotency key in body so re-runs dedupe. Pattern:
|
|
`<!-- idem:<sha16> -->`.
|
|
|
|
## Hard rules (production-incident-driven)
|
|
|
|
1. **Fail-closed defaults** when uncertain about routing / permissions /
|
|
platforms. Default to the safer outcome (no fan-out, no auto-promote,
|
|
no auto-merge). See `_MODULE_PLATFORMS` in
|
|
`claude-worker-universe/core/wen_shu_hub.py` for the canonical pattern.
|
|
2. **Portable links only.** Never write `/Users/...` in commits, issues,
|
|
comments, or test artifacts. Use Gitea web URL with per-segment UTF-8
|
|
percent-encoding. Helper: `_qa_spec_gitea_url`.
|
|
3. **No inline PAT in remote URL.** If you see
|
|
`https://oauth2:<token>@host/...` in a remote, that's an existing
|
|
smell — don't propagate.
|
|
|
|
## References
|
|
|
|
- Master design: `claude-worker-universe/.omc/notes/master-design.md`
|
|
- Build machine review: `dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md`
|
|
- Big-co patterns reused: Stripe Idempotency, Linear AI agents,
|
|
GitHub Copilot for Issues, Datadog rolling-3-window WARN, AWS IAM
|
|
fail-closed.
|