Skip to content

docs(agents): apply named arguments to new calls too - #1975

Merged
JohnVillalovos merged 1 commit into
mainfrom
jlvillal/agents
Nov 19, 2026
Merged

JohnVillalovos merged 1 commit into
mainfrom
jlvillal/agents

Conversation

@JohnVillalovos

Copy link
Copy Markdown
Collaborator

The named arguments rule only covered calls whose arguments are changed, so it was unclear whether a call written from scratch should use them. State that every call that is written or modified uses named arguments, in new and in existing code. Calls that are not otherwise touched are still left alone.

Also drop the exception for calls into lib/external/, so the rule covers third-party code too. The exception had no technical reason: that code is never modified, so its parameter names cannot change. For Composer packages, PHPStan reports an unknown named parameter, so a package that renames one is caught when the dependency is updated.

Because the rule now covers every call, say that a call stays positional when the callee requires it. Built-in variadic functions do: array_merge(arrays: [1]) throws an ArgumentCountError.

The exception for parameter names that are not stable stays.

Assisted-by: Claude:claude-fable-5-2

The named arguments rule only covered calls whose arguments are
changed, so it was unclear whether a call written from scratch
should use them. State that every call that is written or modified
uses named arguments, in new and in existing code. Calls that are
not otherwise touched are still left alone.

Also drop the exception for calls into lib/external/, so the rule
covers third-party code too. The exception had no technical reason:
that code is never modified, so its parameter names cannot change.
For Composer packages, PHPStan reports an unknown named parameter,
so a package that renames one is caught when the dependency is
updated.

Because the rule now covers every call, say that a call stays
positional when the callee requires it. Built-in variadic functions
do: array_merge(arrays: [1]) throws an ArgumentCountError.

The exception for parameter names that are not stable stays.

Assisted-by: Claude:claude-fable-5-2

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are present, and the change is limited to clarifying named-argument guidance and its documented exceptions.

No open issues 🎉

What changed in this PR

Clarifies the named-arguments guidance so it applies to all newly written or modified calls, including calls into third-party code, while preserving required positional-call exceptions.

Changes:

  • Requires named arguments for new and modified calls.
  • Removes the lib/external/ exception.
  • Documents positional exceptions for variadic callees and unstable parameter names.
  • Updates the document’s last-updated date.
File Description
AGENTS.md Updates the named-arguments coding guideline, exceptions, and document metadata date.

Review effort: Lite

@JohnVillalovos
JohnVillalovos enabled auto-merge (rebase) November 19, 2026 01:10
@JohnVillalovos
JohnVillalovos merged commit be8d309 into main Nov 19, 2026
16 checks passed
@JohnVillalovos
JohnVillalovos deleted the jlvillal/agents branch November 19, 2026 01:11
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