Skip to content

docs(agents): an API model's field is described by its docstring, not a doc comment - #2416

Open
eddie-on-gh wants to merge 1 commit into
mainfrom
claude/exciting-dirac-bigla2
Open

eddie-on-gh wants to merge 1 commit into
mainfrom
claude/exciting-dirac-bigla2

Conversation

@eddie-on-gh

Copy link
Copy Markdown
Contributor

Summary

AGENTS.md told agents to put a #: doc comment above a pydantic model's field. pydantic never reads a comment: it takes a field's description from the docstring below it (use_attribute_docstrings, which serve.schema.Model sets) or from Field(description=...). The API models are already written that way, so the rule disagreed with the code. Found while scoping the doc-comments codemod (#2413).

What changes

  • A field of a canopy.serve.schema.Model is described by the docstring directly below it; a comment above it is a note kept out of the schema and stays a plain #.
  • A model whose schema an agent reads, such as a tool's arguments, uses Field(description=...).
  • A pydantic model that publishes no schema, such as the config's, still takes #:.

Tests

  • Ran: make fmt and make lint. Docs only, so no tests.

Docs

  • AGENTS.md, Code conventions. No design or decision change.

Generated by Claude Code

… a doc comment

pydantic reads a field's description from the docstring below it (use_attribute_docstrings) or from
Field(description=...), never from a comment, so the rule that gave a pydantic model's field a #: comment
disagreed with how serve's models are written.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J4hJpwavraAeZtwdiZckZq
@eddie-on-gh
eddie-on-gh marked this pull request as ready for review November 18, 2026 00:11
@sourcery-ai

sourcery-ai Bot commented Nov 18, 2026

Copy link
Copy Markdown

Sorry @eddie-on-gh, this account has used its review budget of 1,500,000 diff characters for the last 7 days.

You can request another review in 20 hours and 6 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@claude

claude Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Claude finished @eddie-on-gh's task in 11s —— View job


Review

No issues found. The new AGENTS.md paragraph matches the code:

  • serve.schema.Model sets use_attribute_docstrings=True (src/canopy/serve/schema/__init__.py:67).
  • serve/schema/ticket.py puts a docstring directly below each field, so it works as the cited example.

Trust model: this PR changes AGENTS.md only. It is a docs-convention change and lets the loop do nothing new. TRUST_MODEL.md, the overseer prompt and .agents/agents/ are untouched. I judged it against the base branch's rules.

Docs-only, so no tests are needed. Line wrapping is within 120.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants