docs(agents): agent rules 更新 — task-tier/worker dispatch 契約 + 補齊 reasoning contract 檔 - #267
Conversation
…oning contract 檔 - AGENTS.md / CLAUDE.md 新增「非平凡/高風險任務先做 task tier 判斷、worker dispatch、 最終回覆分 verified facts / inferences / unverified risks」守則,sub-file 表新增 advanced-agent-reasoning-contract 一列。 - 補入原 commit 指向但僅 untracked、未 commit 的 docs/agents/advanced-agent-reasoning-contract.md,避免文件斷連結。 - 順帶更新 GitNexus banner(8299→17219 symbols;MCP 工具名 gitnexus_* → 新版 impact/context/query/detect_changes)。 來源:本地 commit f6de50e(2026-06-25 update agent rules),rebase 到最新 origin/main 後開 PR。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UoNYrYHRZ2b6qPvfFWobq8
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughThis PR updates agent governance docs to require task-tier evaluation, worker dispatch or justification, and separated evidence labeling in final responses. It also adds a new advanced reasoning contract, rewrites GitNexus instructions, and adds a design spec describing the tier/dispatch rules. ChangesAgent governance and reasoning contract
Estimated code review effort: 2 (Simple) | ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR promotes a local commit (f6de50e, "update agent rules") that adds a new agent reasoning contract to the repo's agent-governance docs. It introduces a docs/agents/advanced-agent-reasoning-contract.md sub-file defining task-complexity tiers, reasoning-effort routing, worker dispatch rules, evidence labeling, and a done gate; wires it into the two main agent entry docs (AGENTS.md / CLAUDE.md) via new work-rule bullets and sub-file index rows; and refreshes the auto-generated GitNexus banner (symbol/relationship counts and new impact/context/query/detect_changes tool names). It fits the repo's lazy-load documentation pattern that keeps the main files under their line budgets.
Changes:
- Adds the new
advanced-agent-reasoning-contract.mdcontract and references it from both main docs (bullets + sub-file table rows kept consistent). - Updates the GitNexus banner identically in
AGENTS.mdandCLAUDE.md(17219 symbols;gitnexus_*→ new tool names). - Line budgets respected (AGENTS.md 217 ≤ 250; CLAUDE.md 124 ≤ 130); the previously-dangling link now resolves.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/agents/advanced-agent-reasoning-contract.md | New sub-file defining reasoning tiers, worker dispatch, evidence labels, and done gate; its §8 source-of-truth ordering conflicts with the repo's canonical ordering. |
| AGENTS.md | Adds work-rule bullet + summary line, new sub-file index row, and refreshed GitNexus banner. |
| CLAUDE.md | Mirrors AGENTS.md: adds work-rule bullet, sub-file index row, and the (newly added) GitNexus banner block. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| For this repo: | ||
|
|
||
| 1. User's latest explicit instruction | ||
| 2. Root `AGENTS.md` and loaded `docs/agents/*.md` contracts | ||
| 3. Code implementation | ||
| 4. Contracts / specs / tests / CI config | ||
| 5. Generated wiki, memory, graph summaries, and old evidence |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/agents/advanced-agent-reasoning-contract.md`:
- Around line 1-8: The document is missing an explicit nature marker required
for docs markdown files. Update Advanced Agent Reasoning Contract near the top
to clearly declare it as a contract using the repo’s document-nature convention,
keeping the rest of the content unchanged. Use the existing heading/content in
Advanced Agent Reasoning Contract as the anchor and add the marker in the
opening section so the file is unambiguously classified.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1f66c20c-0bf6-4bde-a96e-0e5f4036660b
📒 Files selected for processing (3)
AGENTS.mdCLAUDE.mddocs/agents/advanced-agent-reasoning-contract.md
| > Loaded lazily by AGENTS.md / CLAUDE.md. Source-of-truth: AGENTS.md. | ||
| > | ||
| > Read this file when a task is non-trivial, high-risk, asks for audit/review/E2E readiness, or may need worker/subagent decomposition. | ||
|
|
||
| # Advanced Agent Reasoning Contract | ||
|
|
||
| This file defines how agents should route reasoning effort, dispatch workers, label evidence, and finish work in this repo. It does not replace repo boundary, product, GitNexus, deploy, or verification contracts. | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Missing explicit document nature marker.
Per coding guidelines, all docs/**/*.md files MUST mark their document nature as one of: agent boundary / contract / wiki / runbook / spec design / working note. This file is clearly a contract but does not explicitly state this. Add a nature marker near the top.
> Loaded lazily by AGENTS.md / CLAUDE.md. Source-of-truth: AGENTS.md.
>
> Read this file when a task is non-trivial, high-risk, asks for audit/review/E2E readiness, or may need worker/subagent decomposition.
+>
+> **Document nature:** contract
# Advanced Agent Reasoning ContractBased on coding guidelines, docs/**/*.md: MUST mark document nature: agent boundary / contract / wiki / runbook / spec design / working note.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > Loaded lazily by AGENTS.md / CLAUDE.md. Source-of-truth: AGENTS.md. | |
| > | |
| > Read this file when a task is non-trivial, high-risk, asks for audit/review/E2E readiness, or may need worker/subagent decomposition. | |
| # Advanced Agent Reasoning Contract | |
| This file defines how agents should route reasoning effort, dispatch workers, label evidence, and finish work in this repo. It does not replace repo boundary, product, GitNexus, deploy, or verification contracts. | |
| > Loaded lazily by AGENTS.md / CLAUDE.md. Source-of-truth: AGENTS.md. | |
| > | |
| > Read this file when a task is non-trivial, high-risk, asks for audit/review/E2E readiness, or may need worker/subagent decomposition. | |
| > | |
| > **Document nature:** contract | |
| # Advanced Agent Reasoning Contract | |
| This file defines how agents should route reasoning effort, dispatch workers, label evidence, and finish work in this repo. It does not replace repo boundary, product, GitNexus, deploy, or verification contracts. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/agents/advanced-agent-reasoning-contract.md` around lines 1 - 8, The
document is missing an explicit nature marker required for docs markdown files.
Update Advanced Agent Reasoning Contract near the top to clearly declare it as a
contract using the repo’s document-nature convention, keeping the rest of the
content unchanged. Use the existing heading/content in Advanced Agent Reasoning
Contract as the anchor and add the marker in the opening section so the file is
unambiguously classified.
Source: Coding guidelines
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 41eda986e7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. User's latest explicit instruction | ||
| 2. Root `AGENTS.md` and loaded `docs/agents/*.md` contracts | ||
| 3. Code implementation | ||
| 4. Contracts / specs / tests / CI config | ||
| 5. Generated wiki, memory, graph summaries, and old evidence |
There was a problem hiding this comment.
When this new contract is loaded for non-trivial reviews or implementation work, it now tells agents to prefer AGENTS.md and loaded docs/agents/*.md over the code and contracts. That directly conflicts with the existing repo rule in AGENTS.md §3 and docs/AGENTS.md that behavioral correctness comes from code first, then contracts, then AGENTS boundary docs; in any stale-docs scenario this can cause an agent to make or review product/API changes from the wrong authority. Please either preserve the existing code/contracts-first order here or scope this list explicitly to agent-instruction conflicts only.
Useful? React with 👍 / 👎.
| - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. | ||
| - **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "main"})`. |
There was a problem hiding this comment.
This banner switches the mandatory MCP calls to impact(...)/detect_changes(...), but the same entrypoint still says to run gitnexus_impact/gitnexus_detect_changes in §4, and the linked docs/agents/gitnexus-usage.md remains on the old gitnexus_* names. On the next symbol edit or review gate, agents will see conflicting required invocations and may fail or skip the GitNexus validation path; update the lead sentence and linked detailed contract in the same change, or keep the old names consistently.
Useful? React with 👍 / 👎.
| Workers are mandatory when: | ||
|
|
||
| - there are 2+ independent code areas that can be inspected in parallel | ||
| - bug/root-cause investigation has multiple plausible failure layers |
There was a problem hiding this comment.
This makes workers mandatory for every audit or PR review, but the same section also allows skipping workers when the answer depends mainly on direct source-of-truth files or shell/MCP facts. For docs-only or single-file reviews, both rules apply at once, so agents cannot tell whether to dispatch workers or use the documented skip path; narrow this requirement to multi-area/high-risk reviews or state which rule wins.
Useful? React with 👍 / 👎.
- .gitignore:忽略 .workflow/(ultracode 執行痕跡)、artifacts/tmp/、 bim-review-coordinator/track.txt;artifacts/e2e/.gitignore 補齊 Playwright trace 二進位型別(*.zip/*.trace/*.network/*.stacks/*.jpeg/_trace_extract/)。 - docs/agents/github-workflow.md:closeout 清理範本補上 git worktree remove/prune 先於 branch -D;新增「Worktree 生命週期」章節(位置/命名、worktree vs branch-switch、 closeout 前置、與 D 軸部署區分工)。 - 追蹤 project-authored workflow .claude/workflows/plan-next-spec-to-done-aware.js。 - 不動 AGENTS.md / CLAUDE.md(避開 PR #267 併行改動衝突)。 Claude-Session: https://claude.ai/code/session_01VKZSJPSihwExrC1QQBZv8v Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e789535889
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. | ||
| - **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "main"})`. |
There was a problem hiding this comment.
When agents load CLAUDE.md directly, the section lead just above this added banner still requires gitnexus_impact / gitnexus_detect_changes, while the new banner requires impact / detect_changes. Fresh evidence beyond the existing AGENTS.md comment is that this commit now adds the same contradictory banner to the Claude entrypoint, so a symbol edit or commit gate can follow incompatible command names depending on which sentence is read; keep these names aligned with the section lead and docs/agents/gitnexus-usage.md.
Useful? React with 👍 / 👎.
PR body 已補上 AI Coding Governance 表格 7 欄位(誠實反映純文件變更、 無 code symbol、無 CODEOWNERS 需求、無 frontend/deploy 影響),空 commit 用於觸發 pull_request:synchronize 重跑 pr-review-agent check。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
AGENTS.md 變更觸發 Test-PrReviewNeedsOpenSpec,且本 repo 已於 #189 退役 OpenSpec、改用 docs/superpowers/specs/*.md 作為 behavior/workflow 變更的 formal spec evidence(Test-PrReviewHasFormalOpenSpecEvidence)。新增 2026-06-25-agent-rules-task-tier-worker-dispatch-design.md,如實記錄本 PR 新增的 task-tier/worker-dispatch/evidence-labels 規則設計,消除 missing_openspec high blocker。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
PR Review Agent Summary
Blockers
Warnings
Validation Commands
Checks
Human Review Notes
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd718c5075
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 4. **Worker Output Contract**:每個 worker/reviewer 必須回報 Scope / Evidence / Finding / Uncertainty / Risk / Next step,不得只回泛用摘要。 | ||
| 5. **Reviewer Perspectives**:依風險挑 2–5 個視角(正確性、架構/repo 邊界、安全/權限、runtime/deploy/Kit-WebRTC、測試/回歸、UX/使用者可見證據、資料品質、可維護性、成本/context 複雜度)。 | ||
| 6. **Evidence Labels**:最終回覆分 Verified facts / Inferences / Unverified risks / Next action 四段,禁止把文件宣稱、舊記憶、generated wiki、GitNexus/graph 摘要當作 runtime-verified 事實。 | ||
| 7. **Source-of-Truth Priority**:使用者最新指令 > 根目錄 `AGENTS.md` 與已載入的 `docs/agents/*.md` > code 實作 > contracts/specs/tests/CI config > generated wiki/memory/graph 摘要。 |
There was a problem hiding this comment.
Fresh evidence beyond the existing advanced-agent comment is that this line copies the same reversed priority into a formal docs/superpowers/specs design file; docs/AGENTS.md:32 requires docs to keep 程式碼 > contracts > AGENTS 邊界 > wiki, and scripts/lib/pr-review-agent.ps1:254-258 treats these superpowers specs as formal spec evidence. Leaving this order here lets future agent-governance work cite the design spec to prefer stale agent docs over implementation or API contracts, so please keep this code/contracts-first or scope it only to agent-instruction conflicts.
Useful? React with 👍 / 👎.
Summary
把本地 commit
f6de50e(2026-06-25「update agent rules」,未推上 origin)整理後開 PR。advanced-agent-reasoning-contract一列。docs/agents/advanced-agent-reasoning-contract.md,但該檔僅 untracked、從未 commit;本 PR 一併帶入,避免文件引用斷連結。gitnexus_*→ 新版impact/context/query/detect_changes。pr-review-agent對AGENTS.md變更判定missing_openspec(本 repo 已於 chore(skills): 移除 OpenSpec 閉環技能（改採 superpowers 分期落地） #189 退役 OpenSpec,改認docs/superpowers/specs/*.md為 formal evidence);新增docs/superpowers/specs/2026-06-25-agent-rules-task-tier-worker-dispatch-design.md,如實記錄本次規則設計以消除該 blocker。AI Coding Governance
f6de50ethat referenced a never-committed file)docs/superpowers/specs/2026-06-25-agent-rules-task-tier-worker-dispatch-design.md— retroactive formal spec added in this PR (satisfiespr-review-agent'smissing_openspecgate for theAGENTS.mdworkflow change)required_pull_request_reviews; only CI/status checks are required, no reviewer requestedAGENTS.md,CLAUDE.md,docs/agents/advanced-agent-reasoning-contract.md,docs/superpowers/specs/*.md); no code symbol touched, soimpact/detect_changesdo not applyAGENTS.md/CLAUDE.md, plus newdocs/agents/advanced-agent-reasoning-contract.md). Rollback: revert this PR's squash commit; pure doc change with no code dependents, restores prior governance text immediately驗證
git diff --cached --check乾淨。pr-review-agent首輪:check-pr-body-evidence因缺 AI Coding Governance 表格而 FAILURE;補表後該檢查passed,但同 job 內另一獨立步驟(Run PR review agent)回報status=blocked risk=high,原因是missing_openspec(AGENTS.md變更需 formal spec evidence);已補docs/superpowers/specs/2026-06-25-agent-rules-task-tier-worker-dispatch-design.md對應消除。已知風險
gitnexus analyze會再刷新(正常 churn)。pr-review-agent阻擋(先是 PR body evidence 表格全空,後是missing_openspec);目前尚待下一輪 CI 確認兩者皆已消除。🤖 Generated with Claude Code
Summary by CodeRabbit