[AI] Add Agent Readiness Configuration by ParaskP7 · Pull Request #296 · Automattic/Automattic-Tracks-Android

ParaskP7 · 2026-03-04T11:09:19Z

Closes: AINFRA-2083

Description

Add coding agent readiness configuration following the coding agents guidelines (PCYsg-1bzA-p2). This sets up the repository so that coding agents can understand the project structure, build commands, conventions, and gotchas without manual guidance.

Changes:

Add CLAUDE.md auto-generated via /init, then updated to reference AGENTS.md via the @AGENTS.md directive
Add AGENTS.md as the single source of truth for all coding agents, documenting project overview, build commands, architecture, testing conventions, and important gotchas
Add .aiexclude to restrict agent access to build artifacts while allowing reports, outputs, and test results
Update .gitignore with local override patterns for popular coding agents (Claude, Codex, Gemini, Cursor, Windsurf) and remove a duplicate IntelliJ block. Junie and Copilot are excluded as Junie's entire directory is local and Copilot has no local override pattern

Assessment:

Category	Status	Reasoning
1. Guidelines	Done	`AGENTS.md` documents project overview, build commands, architecture, testing conventions, and gotchas. `CLAUDE.md` points to it via `@AGENTS.md`. `.aiexclude` restricts access to build artifacts and sensitive files.
2. Build & Tests	Done	An agent can build (`./gradlew assembleDebug`), run tests (`./gradlew testDebugUnitTest`), lint (`./gradlew lintDebug`), and check code style (`./gradlew ktlint`) — all documented in `AGENTS.md`. The bootstrap step (`cp gradle.properties-example gradle.properties`) is also documented. CI already runs all of these via Buildkite.
3. E2E Verification	TODO	This is a library, not an app with user-facing UI. There's no E2E framework (no Espresso, UI Automator, Maestro). The `sampletracksapp` exists for manual testing but there's no automated E2E path. The `benchmark` module has instrumented tests but those measure performance, not user-facing behavior.
4. Isolated Env	Done	`.java-version` (21) and Gradle wrapper (9.0.0) are pinned. `gradle.properties-example` serves as the env template. `.gitignore` includes agent local override patterns for all major coding agents. No additional setup scripts or containers needed for this library.

Testing Steps

Verify CLAUDE.md contains only @AGENTS.md
Verify AGENTS.md documents build commands, architecture, testing conventions, and gotchas
Verify .aiexclude excludes build artifacts but allows reports/, outputs/, and test-results/
Verify .gitignore includes local override patterns for agent config files and no longer has duplicate IntelliJ block

Add CLAUDE.md at the repository root, auto-generated via the `/init` command, documenting project overview, build commands, architecture, testing conventions, important gotchas, and publishing details to help coding agents operate effectively in this codebase. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Guide: https://fieldguide.automattic.com/coding-agents-guidelines Move project guidance content into AGENTS.md as the single source of truth for all coding agents, per the Fieldguide coding agents guidelines. Update CLAUDE.md to reference AGENTS.md via the @AGENTS.md directive. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update AGENTS.md to use agent-agnostic heading and description. Add ktlint, ktlintFormat custom tasks with source reference, benchmark androidTest tasks, sample app mention, and clarify experimentation module name in apiCheck comment. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add .aiexclude file to prevent coding agents from reading build outputs, gradle caches, and local/gradle properties while allowing access to reports, outputs, and test results. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add gitignore patterns for coding agent local override files. Covers AGENTS.local.md and CLAUDE.local.md for repo-level overrides, plus local files for Claude, Codex, Gemini, Cursor, and Windsurf agent directories. Junie and Copilot are excluded as Junie's entire directory is local and Copilot has no local override pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds repository-level “agent readiness” configuration so coding agents can quickly understand how to build/test the project and which files to avoid reading (e.g., build artifacts and local secrets).

Changes:

Add AGENTS.md as the primary agent-facing project guide (overview, build/test commands, architecture, conventions, gotchas).
Add CLAUDE.md that delegates to AGENTS.md via @AGENTS.md.
Add .aiexclude and update .gitignore to limit agent exposure to build artifacts and ignore agent-local override files.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
`CLAUDE.md`	Adds a single directive to reference `AGENTS.md`.
`AGENTS.md`	Introduces a consolidated guide for agent workflows and repo conventions.
`.aiexclude`	Excludes build artifacts and local config files, with allowlist-style exceptions for reports/outputs/test-results.
`.gitignore`	Removes a duplicate IntelliJ block and adds patterns to ignore agent-local override files.

Comments suppressed due to low confidence (1)

CLAUDE.md:2

CLAUDE.md currently includes a trailing blank line. If the consuming agent tooling expects the file to contain only the single @AGENTS.md directive, consider removing the extra empty line so the file is exactly one line long.

@AGENTS.md

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

Copilot · 2026-03-04T11:15:15Z

.aiexclude

+build/
+!build/reports/
+*/build/


If .aiexclude uses gitignore-style semantics (the patterns/negation syntax suggest it does), !build/reports/ (and the similar module rules) won’t take effect because the parent build/ directory is excluded. To ensure reports/outputs/test-results are actually included, un-exclude the parent directories and then re-exclude everything else (e.g., unignore build/ + selectively allow subpaths), or restructure the patterns accordingly.

Suggested change

build/

!build/reports/

*/build/

build/*

!build/reports/

*/build/*

TIL about .aiexclude. Neat. Hopefully it takes hold as a wider standard.

Regarding the syntax, Copilot's suggestion is good. From the docs:

An .aiexclude file follows the same syntax as a .gitignore file.

Hopefully it takes hold as a wider standard.

🤞 x 🤞 ^ 🤞

Copilot · 2026-03-04T11:15:15Z

AGENTS.md

+./gradlew testDebugUnitTest          # Run all unit tests
+./gradlew lintDebug                  # Run lint checks


The documented lint/test commands (lintDebug, testDebugUnitTest) don’t match what CI runs (./gradlew lint and ./gradlew test per .buildkite/pipeline.yml). Consider documenting the CI-equivalent tasks (or noting the difference) so agents reproduce CI locally without guessing the right task names.

Suggested change

./gradlew testDebugUnitTest # Run all unit tests

./gradlew lintDebug # Run lint checks

./gradlew testDebugUnitTest # Run unit tests for the debug variant (CI runs `./gradlew test`)

./gradlew lintDebug # Run lint checks for the debug variant (CI runs `./gradlew lint`)

mokagio

Looking good. Only nitpicks

mokagio · 2026-03-13T02:27:23Z

.aiexclude

+build/
+!build/reports/
+*/build/


TIL about .aiexclude. Neat. Hopefully it takes hold as a wider standard.

Regarding the syntax, Copilot's suggestion is good. From the docs:

An .aiexclude file follows the same syntax as a .gitignore file.

mokagio · 2026-03-13T02:31:40Z

.gitignore

+**/AGENTS.local.md
+**/CLAUDE.local.md


I didn't know these were a thing. The docs don't mention supporting a CLAUDE.local.md file.

However, it seems to be working

Not sure if it's a compatibility thing that they'll phase out, as it's not documented, or just a standard pattern that will be maintained.

Yea, same @mokagio and thanks for taking a closer look at it, plus testing it! 🥇

I too just found it myself as I was writing those Agent Readiness PRs, of course with AI help and support, and thought, why not adding those in there, wouldn't hurt, would it? Worse case scenario, I thought, we'll stop adding them into more repos (should that not become a standard), and maybe, delete this configuration from those repos that we've added them in already, right? Having said that, usually, this .gitignore file becomes a fire and forget file, with ignore files/folders been added in there but rarely removed/edited, only when REALLY needed... 🤷

why not adding those in there, wouldn't hurt, would it?

Yes, I don't see any problems (other than bloat maybe) in having that in the .gitignore. Can always be removed in a future where it's no longer supported.

(other than bloat maybe)

True @mokagio ! 👍

Can always be removed in a future where it's no longer supported.

💯

mokagio · 2026-03-13T02:33:19Z

AGENTS.md

+- Build files use **Groovy** (`build.gradle`, `settings.gradle`), not Kotlin DSL — except `benchmark/build.gradle.kts` which uses Kotlin DSL
+- Dependency versions are defined as `ext` properties in root `build.gradle`, not a version catalog
+- Lint treats warnings as errors (`warningsAsErrors true`). `AutomatticTracks` uses a lint baseline file


The first and last seem like stuff the model would notice when reading the code, without needing to be explicit

Suggested change

- Build files use **Groovy** (`build.gradle`, `settings.gradle`), not Kotlin DSL — except `benchmark/build.gradle.kts` which uses Kotlin DSL

- Dependency versions are defined as `ext` properties in root `build.gradle`, not a version catalog

- Lint treats warnings as errors (`warningsAsErrors true`). `AutomatticTracks` uses a lint baseline file

- Dependency versions are defined as `ext` properties in root `build.gradle`, not a version catalog

Good comment @mokagio ! 💯

I was thinking about that too, in the end chose to keep it in there because this version catalog is indeed the standard nowadays (years now), and I think AI would try to enforce this standard, maybe creating such a version catalog pattern, that is, instead of using the existing legacy ext properties pattern this repo uses. What I wanted here, is for AI to avoid doing that, thinking in version catalog terms, thus me being explicit giving it instructions on how dependency versions are and should be defined on this repo, being (somehow) explicit that we DON'T WANT version catalog. Does that make any sense to you? 💭 (I probably over-complicating this 😊 for sure)

Thanks for clarifying. That makes sense to me.

Just to be clear, I am suggesting to remove the "Build files use Groovy" and "Lint treats warnings as errors..." entries because that info is already specified in the document and to keep the version catalog note, which appears in the gotchas for the first time.

Ah, 🤦 here @mokagio , and thanks for keeping at it with me... for some reason I read the commit suggestion and that got my brain confused, thinking this comment was about that, while it was about everything else but that, not sure what happened there, apologies... 🫣

Build files use Groovy (build.gradle, settings.gradle), not Kotlin DSL — except benchmark/build.gradle.kts which uses Kotlin DSL

I would still keep that in there because it is not making sure that AI knows that Groovy is the standard in there and not Kotlin DSL, except for this one module, just to avoid confusion and help AI chose the right standard. 🤔

Lint treats warnings as errors (warningsAsErrors true). AutomatticTracks uses a lint baseline file

We could definitely remove that, I agree, will do! 👍

Sounds good.

This is now done: b66e127 Cc @mokagio

mokagio · 2026-03-16T02:53:16Z

Ship it

Remove the lint warnings-as-errors gotcha from the important gotchas section as it is discoverable by agents when reading the build files directly. PR Comment: #296 (comment) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ParaskP7 and others added 6 commits March 4, 2026 12:26

Git: Remove duplicate intellij project files block

f2d69b6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ParaskP7 added the enhancement label Mar 4, 2026

ParaskP7 requested a review from Copilot March 4, 2026 11:10

Copilot started reviewing on behalf of ParaskP7 March 4, 2026 11:11 View session

ParaskP7 added ai documentation labels Mar 4, 2026

Copilot AI reviewed Mar 4, 2026

View reviewed changes

ParaskP7 marked this pull request as ready for review March 4, 2026 11:28

ParaskP7 requested a review from mokagio March 4, 2026 11:28

mokagio approved these changes Mar 13, 2026

View reviewed changes

AI: Remove lint gotcha from agents.md per code review

b66e127

Remove the lint warnings-as-errors gotcha from the important gotchas section as it is discoverable by agents when reading the build files directly. PR Comment: #296 (comment) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ParaskP7 merged commit b372138 into trunk Mar 17, 2026
11 checks passed

ParaskP7 deleted the ai/add-agent-readiness-configuration branch March 17, 2026 08:45

		./gradlew testDebugUnitTest # Run all unit tests
		./gradlew lintDebug # Run lint checks

		**/AGENTS.local.md
		**/CLAUDE.local.md

Conversation

ParaskP7 commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes:

Assessment:

Testing Steps

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

mokagio left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mokagio commented Mar 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ParaskP7 commented Mar 4, 2026 •

edited

Loading