Canonical approach to supporting AI agent directions #16735

titusfortner · 2025-12-15T21:47:36Z

User description

Reason for PR

Need a single summary of the project that is short and easily parsable by AI coding agents to better understand the repo.
Goal is only information that is useful in every context window when working with Selenium using Codex or Claude Code, etc

💥 What does this PR do?

Adds primary AGENTS.md file with overview of project so agents can better understand the repo
Adds AGENTS.md files in each of the language directories for language specific information
Points CLAUDE.md and .github/copilot-instructions.md to AGENTS.md
Adds the other popular AI tooling directories & files to .gitignore

🔧 Implementation Notes

Split the file into multiple files to minimize what agents must store in context window, so if a dev is only working in one language binding, the agent only has to work with that agents file.

💡 Additional Considerations

This PR assumes the TESTING.md files created in #16734 exist

PR Type

Documentation

Description

Adds comprehensive AGENTS.md files for AI coding agent guidance
Creates language-specific agent documentation in each binding directory
Redirects CLAUDE.md and copilot-instructions.md to primary AGENTS.md
Provides standardized instructions for AI agents working in Selenium monorepo

Diagram Walkthrough

flowchart LR
  A["Root AGENTS.md<br/>Monorepo Overview"] --> B["java/AGENTS.md<br/>Java Binding Guide"]
  A --> C["py/AGENTS.md<br/>Python Binding Guide"]
  A --> D["rb/AGENTS.md<br/>Ruby Binding Guide"]
  A --> E["javascript/AGENTS.md<br/>JavaScript Binding Guide"]
  A --> F["dotnet/AGENTS.md<br/>.NET Binding Guide"]
  A --> G["rust/AGENTS.md<br/>Rust/Manager Guide"]
  H["CLAUDE.md"] -.->|references| A
  I["copilot-instructions.md"] -.->|references| A

File Walkthrough

Relevant files

Documentation

9 files

AGENTS.md `Root agent guidance for monorepo overview`	+64/-0
CLAUDE.md `Redirect to primary AGENTS.md file`	+1/-0
copilot-instructions.md `GitHub Copilot instructions redirect`	+1/-0
AGENTS.md `Java bindings and Grid agent guidance`	+15/-0
AGENTS.md `Python bindings agent guidance`	+15/-0
AGENTS.md `Ruby bindings agent guidance`	+16/-0
AGENTS.md `JavaScript bindings agent guidance`	+12/-0
AGENTS.md `.NET bindings agent guidance`	+15/-0
AGENTS.md `Rust and Selenium Manager agent guidance`	+13/-0

qodo-code-review · 2025-12-15T21:47:57Z

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

qodo-code-review · 2025-12-15T21:49:00Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	✅ ~~Separate concatenated shell commands~~ Suggestion Impact: The combined command line was changed by separating out (and keeping) only the `bazel build //rb/...` part, removing the concatenated `bazel run //:bundle -- update` from that line. However, the second suggested list item was not added in this patch. code diff: ## Common commands -- `bazel build //rb/... bazel run //:bundle -- update` +- `bazel build //rb/...` Separate the single-line `bazel build` and `bazel run` commands in the "Common commands" section into two distinct list items for clarity and correct execution. rb/AGENTS.md [8-9] ## Common commands -- `bazel build //rb/... bazel run //:bundle -- update` +- `bazel build //rb/...` +- `bazel run //:bundle -- update` `[Suggestion processed]` Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies two concatenated commands that would fail if run as written, and proposes splitting them for clarity and to ensure correct execution by an AI agent.	Medium
Possible issue	✅ ~~Include JavaScript binding in search command~~ Suggestion Impact: The documentation was updated to include `javascript/selenium-webdriver/` in the cross-binding `rg ` command under "Cross-binding consistency checks", ensuring JavaScript bindings are searched alongside java/py/rb/dotnet. code diff: +## Cross-binding consistency checks +When changing user-visible behavior, compare with at least one other binding: +- `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/` Add the JavaScript binding path (`javascript/selenium-webdriver/`) to the example `rg` search command to ensure all relevant bindings are checked for changes. AGENTS.md [26-27] When changing behavior, compare to the equivalent areas in at least one other binding: -- `rg <term> java/ py/ rb/ dotnet/` +- `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/` `[Suggestion processed]` Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the `rg` command is missing the JavaScript binding path, which could lead to inconsistent changes across bindings if an AI agent uses this instruction.	Low
General	✅ ~~Replace placeholder with an explanatory comment~~ Suggestion Impact: The commit removed the entire "Dependency management" section containing the '???' placeholder, eliminating the ambiguous placeholder rather than replacing it with a TBD comment. code diff: -## Dependency management -??? - Replace the '???' placeholder in the .NET dependency management section with a more descriptive comment indicating the process is to be determined. dotnet/AGENTS.md [11-12] ## Dependency management -??? +<!-- TBD: The dependency management process for .NET is not yet documented for AI agents. --> `[Suggestion processed]` Suggestion importance[1-10]: 4 __ Why: The suggestion improves the clarity of the documentation by replacing an ambiguous placeholder with an explicit comment, which is more helpful for both human and AI readers.	Low
Update

CLAUDE.md

rb/AGENTS.md

titusfortner · 2026-01-19T15:43:46Z

Thanks for feedback on this; I've been using it locally and I think this is good enough to use. Can definitely use more tweaks going forward.

Copilot

Pull request overview

This PR establishes a canonical approach for providing AI coding agent guidance across the Selenium monorepo. It creates a centralized AGENTS.md file with project-wide context and language-specific AGENTS.md files in each binding directory, redirecting existing AI tool configuration files (CLAUDE.md and copilot-instructions.md) to this new structure.

Changes:

Adds root AGENTS.md with monorepo overview, toolchain details, testing guidelines, and high-risk area identification
Creates language-specific AGENTS.md files (Java, Python, Ruby, JavaScript, .NET, Rust) with code conventions, logging patterns, and deprecation guidelines
Redirects CLAUDE.md and .github/copilot-instructions.md to the primary AGENTS.md
Updates .gitignore to exclude common AI agent directories and configuration files
Updates README.md with corrected Ruby development setup commands

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
AGENTS.md	Root-level AI agent guidance covering monorepo structure, toolchain, testing, and cross-binding considerations
CLAUDE.md	Minimal redirect to AGENTS.md for Claude AI integration
.github/copilot-instructions.md	GitHub Copilot redirect to AGENTS.md
java/AGENTS.md	Java-specific code conventions, logging, and Grid guidance
py/AGENTS.md	Python-specific conventions with Google-style docstrings and type hints
rb/AGENTS.md	Ruby-specific guidance including RBS type signatures and YARD documentation
javascript/selenium-webdriver/AGENTS.md	JavaScript-specific conventions with JSDoc patterns
dotnet/AGENTS.md	.NET-specific guidance including async patterns and XML documentation
rust/AGENTS.md	Rust and Selenium Manager specific conventions
.gitignore	Adds AI agent tool directories, local state files, and .local/ directory exclusions
README.md	Corrects Ruby development commands and interpreter paths
.local/.gitkeep	Placeholder for agent-generated artifacts directory

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

AGENTS.md

rust/AGENTS.md

README.md

.local/.gitkeep

CLAUDE.md

java/AGENTS.md

rust/AGENTS.md

README.md

AGENTS.md

Co-authored-by: Copilot <[email protected]>

titusfortner requested review from diemol, jimevans, p0deje, pujagani and shs96c December 15, 2025 21:47

selenium-ci added C-py Python Bindings C-rb Ruby Bindings C-dotnet .NET Bindings C-java Java Bindings C-nodejs JavaScript Bindings B-build Includes scripting, bazel and CI integrations C-rust Rust code is mostly Selenium Manager B-manager Selenium Manager labels Dec 15, 2025

qodo-code-review bot added the Review effort 1/5 label Dec 15, 2025

p0deje approved these changes Dec 16, 2025

View reviewed changes

CLAUDE.md Show resolved Hide resolved

aguspe reviewed Dec 16, 2025

View reviewed changes

rb/AGENTS.md Outdated Show resolved Hide resolved

titusfortner added 4 commits January 19, 2026 09:37

create agents files

ede477c

ignore common AI directories and files

ae4dd16

add section on how to run bazel commands.

7556866

Overhaul from feedback

976e6cf

titusfortner force-pushed the agents branch from 57cfb3a to 976e6cf Compare January 19, 2026 15:41

titusfortner requested a review from Copilot January 19, 2026 15:42

Copilot started reviewing on behalf of titusfortner January 19, 2026 15:42 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Apply suggestions from code review

3108e9b

Co-authored-by: Copilot <[email protected]>

titusfortner merged commit 5df354c into trunk Jan 19, 2026
20 checks passed

titusfortner deleted the agents branch January 19, 2026 16:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Canonical approach to supporting AI agent directions #16735

Canonical approach to supporting AI agent directions #16735

titusfortner commented Dec 15, 2025 •

edited by qodo-code-review bot

Loading

Uh oh!

qodo-code-review bot commented Dec 15, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Dec 15, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

titusfortner commented Jan 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Canonical approach to supporting AI agent directions #16735

Canonical approach to supporting AI agent directions #16735

Conversation

titusfortner commented Dec 15, 2025 • edited by qodo-code-review bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Reason for PR

💥 What does this PR do?

🔧 Implementation Notes

💡 Additional Considerations

PR Type

Description

Diagram Walkthrough

File Walkthrough

Uh oh!

qodo-code-review bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Compliance Guide 🔍

Uh oh!

qodo-code-review bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Uh oh!

Uh oh!

Uh oh!

titusfortner commented Jan 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

titusfortner commented Dec 15, 2025 •

edited by qodo-code-review bot

Loading

qodo-code-review bot commented Dec 15, 2025 •

edited

Loading

qodo-code-review bot commented Dec 15, 2025 •

edited

Loading