From a5d6043bf656c015227348345d7a0a63336526ba Mon Sep 17 00:00:00 2001 From: liuhailong <857688528@qq.com> Date: Sat, 26 Sep 2026 10:30:21 +0800 Subject: [PATCH] docs: codify agent-workflow discipline learned in production Record the hard-won rules in the feedback-driven workflow section: live self-check of render paths before acceptance, PID-only process signaling (pattern kills hit unrelated instances), test isolation env vars and teardown handle hygiene (enforced by the test:release-tools lint), and the current subagent model-route matrix with mid-task route-swap procedure. --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index cd5cdf71..3c792959 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,6 +70,13 @@ User feedback on the running app is handled by an orchestrating agent that deleg - **Accept.** An independent acceptance subagent (model route `zai-coding-cn/GLM-5.3-Flash`; never the instance that wrote the code) reviews the diff against the ticket's acceptance criteria, runs the targeted gates (`pnpm typecheck`, `pnpm build`, and the test suites touching the change), and for UI-visible changes verifies the behavior in a browser with screenshots against the dev server (`pnpm webui:dev`, frontend at `http://127.0.0.1:18091/`). The full `pnpm verify` profile is left to CI. - **Ship.** Open a pull request that references the ticket and attaches the acceptance report (diff verdict, gates run, evidence screenshots). Enable auto-merge (squash); the PR merges once CI is green, and the branch is deleted. Direct pushes to the default branch remain forbidden. +Discipline learned the hard way — apply in every round: + +- **Self-check before acceptance.** The development subagent live-verifies every render path in its own isolated instance before acceptance sees the change; acceptance is never the first pair of eyes on a render path. Pin render-critical wiring with a regression test — a static-source tripwire is acceptable only when the suite has no render harness — and drive internal code paths in tests, not just exported names (an export-alias reference bug once shipped dead code that its own unit tests passed). +- **Process safety.** Never signal processes by name or pattern (`pkill`, `killall`, process-group kills) — they hit unrelated instances, including other agents' test servers and the live dev instance. Signal only PIDs you personally spawned, verified with `ps` first. Isolated test instances run on their own ports with their own `MCODE_WEBUI_DATA_DIR`. +- **Test hygiene.** Tests that spawn `server.js` must set `MCODE_WEBUI_{SETTINGS_PATH,EVENTS_PATH,SESSIONS_DB,UPLOAD_DIR}` to per-test temporary paths — enforced by `scripts/test-isolation-lint.check.mjs` in the `test:release-tools` gate. Close every server/socket in teardown; one leaked handle hangs an entire gate (this failed CI twice). +- **Model routes.** Verify route availability in the session's model catalog before dispatching. Development: `minimax-cn/MiniMax-M3`, with `zai-pro/GLM-5.3` preferred for backend work and `zai-pro/GLM-5.3-Flash` for frontend work when those routes are allowed. Acceptance: the configured reviewer route (e.g. `mimo-pro/mimo-v2.6-pro`), falling back to `zai-coding-cn/GLM-5.3-Flash` — always an instance that did not write the code. A route that fails mid-task is swapped immediately and the work handed over with explicit context; the orchestrator recovers wedged dev-server processes by verified PID only. + ## Boundaries Do not reference internal hosts, generated IDL, or private services; `check:source` catches known patterns but does not replace publication review. Do not restore paths listed in `scripts/lib/retired-sources.mjs` or remove supported capabilities to make standalone checks pass. Do not commit account data, sessions, logs, credentials, or real user content; use temporary data directories and synthetic test inputs. Documentation and commit messages are written in English; preserve the required languages of localized product strings and bundled runtime prompts. See `CONTRIBUTING.md`.