docs: modernize development guidelines and rename to AGENTS.md#2413
docs: modernize development guidelines and rename to AGENTS.md#2413
Conversation
Remove outdated and generic guidance, add project-specific context that
prevents real review churn.
Removed:
- Error Resolution section (generic 'add None checks / test thoroughly')
- Ruff line-wrapping advice (ruff format handles it) and wrong '88 chars'
- Stale pre-commit guidance ('update config rev' - ruff is repo: local)
- Reported-by / Github-Issue commit trailers (unused in practice)
- Duplicate co-authored-by note and generic PR prose
- Generic Code Quality bullets ('focused and small', 'follow patterns')
Added:
- Branching Model: main is the V2 rework, no @deprecated shims, README.md
is frozen (edit README.v2.md), [v1.x] backport prefix
- Dependency floor policy: don't raise floors for CVEs alone (refs
Kludex/uvicorn#2643, #1552)
- __all__ in src/mcp/__init__.py defines the public API surface
- Avoid new pragma/type:ignore/noqa; assert isinstance in tests; audit grep
- filterwarnings=['error'] context for the no-silence-warnings rule
- --frozen on all uv commands; --python <ver> for cross-version testing
- Tests: in-memory > threads > subprocesses; Client(server) for E2E
Restructured numbered-list-in-list into flat H2 sections with a dedicated
Coverage subsection.
AGENTS.md is the emerging tool-agnostic convention (agents.md spec) and is already canonical in the spec repo, kotlin-sdk, ruby-sdk, go-sdk, and inspector. python-sdk and typescript-sdk were the remaining outliers. CLAUDE.md becomes a one-line @AGENTS.md import so Claude Code continues to load the guidelines (Claude Code reads CLAUDE.md, not AGENTS.md natively). Using @-import rather than a symlink for Windows checkout compatibility, matching ruby-sdk and inspector.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
- Fix test-mirror example to use a path that actually exists (src/mcp/client/stdio.py -> tests/client/test_stdio.py) - Add upstream-library carve-out to the filterwarnings rule, since pyproject.toml already has scoped ignore:: entries for websockets/pywin32 - Document Raises: sections for public APIs that raise catchable exceptions
There was a problem hiding this comment.
LGTM — all prior review feedback has been addressed.
Extended reasoning...
Overview
Docs-only PR: renames CLAUDE.md → AGENTS.md with modernized content, adds a one-line CLAUDE.md import stub, and removes a stale filterwarnings entry from pyproject.toml. No production code paths are touched.
Security risks
None. Documentation and a removed dead test-warning suppression entry carry no security surface.
Level of scrutiny
Low. All changes are either instructional prose or the removal of a vestigial pyproject.toml entry (mcp.server.lowlevel filterwarnings) that the author confirmed is absent from the V2 source tree.
Other factors
Four rounds of prior inline comments identified documentation inaccuracies (wrong test-mirror example, incomplete filterwarnings description, missing CI matrix dimension, Windows strict-no-cover caveat, missing UV_FROZEN=1 explanation). All are marked resolved, and the git log confirms corresponding fix commits. The bug hunting system found no new issues in this revision.
1 participant
Modernizes the development guidelines (was 174 lines, now 132) and renames
CLAUDE.mdtoAGENTS.mdto align with the rest of the modelcontextprotocol org.Motivation and Context
The existing
CLAUDE.mdhad accumulated guidance that was outdated, factually wrong (line length stated as 88, pre-commit instructions referenced a ruffrevthat doesn't exist), or generic enough to add no value ("functions must be focused and small", "test thoroughly"). At the same time it was missing project-specific context that causes recurring review churn, most notably the V2 branching model and the policy on coverage pragmas.Separately, most repos in this org (
modelcontextprotocol,kotlin-sdk,ruby-sdk,go-sdk,inspector) have already moved toAGENTS.mdas the canonical, tool-agnostic guidelines file per the agents.md convention.python-sdkandtypescript-sdkwere the remaining outliers.Removed
ruff formathandles these; "88 chars" was wrong)repo: local, there is no rev)Reported-by:/Github-Issue:#commit trailers (not used in practice)Added
mainis currently the V2 rework (no@deprecatedshims),v1.xis the release line,README.mdis frozensrc/mcp/__init__.py__all__defines the public API surface# pragma/# type: ignore/# noqa, with an audit grepfilterwarnings = ["error"]context for the no-warning-silencing rule--frozenon alluvcommands;--python <ver>for cross-version testingRename
CLAUDE.md→AGENTS.mdviagit mv(history preserved with--follow). A new one-lineCLAUDE.mdcontaining@AGENTS.mdis added so Claude Code continues to load the file. The@-import is used rather than a symlink for Windows checkout compatibility, matchingruby-sdkandinspector.How Has This Been Tested?
uv run --frozen pre-commit run --files CLAUDE.md AGENTS.mdpasses (markdownlint, end-of-file-fixer). Verifiedgit log --follow AGENTS.mdtraces back through the full CLAUDE.md history. Factual claims cross-checked againstpyproject.toml,.pre-commit-config.yaml, andscripts/test.Breaking Changes
None.
Types of changes
Checklist
Additional context
Split into two commits so
git log --follow AGENTS.mdworks: the content rewrite changed too much for git's rename detection to track it in a single commit, so commit 1 modernizes the content in place and commit 2 is a pure rename plus the import stub.