chore: add agent instruction guidance#1273
Conversation
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ 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 |
Refactor pass on all 13 AGENTS.md files (CLAUDE.md symlinks managed by
scripts/sync-agent-instructions.mjs):
- Add nested AGENTS.md for a2a, mcp, observability, tool, server-core,
and website (Docusaurus-specific gotchas: npm vs pnpm, sucrase-built
plugins, llms.txt is hand-curated, SSR rule, multiple sidebars).
- Rewrite root: split commit/PR conventions, replace contributor-docs
bullets with a Vercel <docs-index> block that includes the website
doc tree, audit Boundaries (lockfile, .changeset/, .github/, tsconfig,
workspace yaml), drop generic "TypeScript-first" Code Style.
- Standardize layout: Critical Rules (bullets, top), Boundaries
(3-tier bullets), "Related" instead of "See Also".
- Fact-check pass against actual source (3 verifier agents):
- Tool span name is `tool.execution:<name>`, not `agent.tool.<name>`.
- Workflow span name is `workflow.step.<stepType>`, not `<stepId>`.
- Agent root span uses the agent's own `name`, not `agent.generateText`.
- `agent.state` enum is running/completed/cancelled.
- Subagent delegate is a single `delegate_task` tool, not `__delegate_to_<name>`.
- `tools` option type is `(Tool | Toolkit)[]`.
- Add `onStepFinish` to the public hook list.
- Replace fabricated `workflow.resume(...)` with real `result.resume()` /
`workflow.run(input, { resumeFrom })`.
- Replace fabricated `client.actions.execute(...)` with namespaced API
(`client.actions.slack.postMessage`, etc.).
- Fix VectorAdapter shape (deleteBatch, no count/get) and
EmbeddingAdapter.getDimensions(): number.
- Rename AISdkEmbeddingAdapter -> AiSdkEmbeddingAdapter.
- server-core: LogStreamManager, drop non-existent test:single script.
- mcp: SDK is range-pinned (caret); default timeout 60000ms not 30000ms.
- workspace: operationTimeoutMs has no default for general ops; fix
stale spec paths; default search mode is conditional.
--no-verify used because lint-staged + Prettier 3.x errors on the
CLAUDE.md symlinks ("Explicitly specified pattern ... is a symbolic
link"). All files were pre-validated with `prettier --check` and pass.
Co-Authored-By: Claude <noreply@anthropic.com>
Switches the root lint-staged config from a static block in package.json
to lint-staged.config.mjs so we can filter files programmatically. Skips:
- AGENTS.md — canonical coding-agent instruction docs; hand-curated, not
worth mechanical Prettier churn.
- CLAUDE.md — symlinks to AGENTS.md (managed by
scripts/sync-agent-instructions.mjs). Prettier 3.x errors when handed
symlink paths explicitly ("Explicitly specified pattern ... is a
symbolic link"), which broke the pre-commit hook on AGENTS.md changes
even when the underlying content was fine.
Updates the husky pre-commit hook to drop `--config package.json` so
lint-staged auto-discovers `lint-staged.config.mjs`.
Also adds AGENTS.md and CLAUDE.md to .prettierignore as a defense-in-depth
measure for direct `prettier --write` runs.
Co-Authored-By: Claude <noreply@anthropic.com>
2 participants
Status
Draft PR, still in progress.
Goals
Current Scope
Still In Progress
Summary by cubic
Make
AGENTS.mdthe single source of truth for coding‑agent instructions, standardize guidance across core, server, and website, and add a script to syncCLAUDE.mdsymlinks. Also harden pre‑commit formatting by movinglint-stagedto a JS config and skipping instruction files to avoid Prettier symlink errors.New Features
AGENTS.mdforpackages/coresub-areas (agent, memory, workflow, workspace, voltops, a2a, mcp, observability, tool) pluspackages/server-coreandwebsite/(Docusaurus rules: npm not pnpm, sucrase-built plugins, hand‑curatedstatic/llms.txt).CLAUDE.md -> AGENTS.mdsymlink aliases;scripts/sync-agent-instructions.mjspreviews, reports conflicts, and supports--yes.AGENTS.mdreorganized with Critical Rules, Boundaries, and Related; adds validation commands,safeStringifyusage, and model‑registry generation.Refactors
contributing/*(coding‑agents, linting, tooling, testing, changesets); removeddocs/linting.mdand.cursor/rules/agents.mdc..gitignoreto ignore local agent/IDE config while keeping shared instruction files tracked.lint-stagedtolint-staged.config.mjs, updated Husky pre‑commit to auto‑discover it, and addedAGENTS.md/CLAUDE.mdto.prettierignoreto prevent Prettier 3.x symlink errors.AGENTS.mdfiles (e.g., tool spantool.execution:<name>, workflow spanworkflow.step.<stepType>,(Tool | Toolkit)[]type, MCP SDK pinning, workspace timeout notes).Written for commit 4cfa777. Summary will update on new commits.