Skip to content

Docs: add a minimal AGENTS.md - #1195

Draft
whyisjake wants to merge 1 commit into
developfrom
docs/agents-md
Draft

Docs: add a minimal AGENTS.md#1195
whyisjake wants to merge 1 commit into
developfrom
docs/agents-md

Conversation

@whyisjake

@whyisjake whyisjake commented Oct 15, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

What?

See #307. Follow up to #308 and #225.

Adds a minimal AGENTS.md and stops ignoring it. Also adds one line to CONTRIBUTING.md about keeping docblocks short.

Why?

Reviews keep catching the same things in AI-assisted PRs. On #1181, @dkotter flagged long AI-written docblocks and tests that only check wiring. Agents don't read reviewer preferences that live only in review threads, so the same comments come back on the next PR.

#308 was closed partly because the docs needed cleaning up first. That happened in #225. Afterwards, @justlevine suggested the repo would be ready for "a minimal AGENTS.md (docs entrypoint, abridged directory tree, important scripts)". This follows that shape.

How?

  • AGENTS.md (about 45 lines), which:
    • points to CONTRIBUTING.md first, then DEVELOPER_GUIDE.md, ARCHITECTURE_OVERVIEW.md and TESTING.md, saying what each is for rather than repeating them;
    • gives a five-line layout and the npm scripts, noting that the PHP scripts run inside wp-env;
    • has two code-style rules: keep comments to a summary line plus the required tags, and test behavior rather than wiring (reusing tests/e2e-testing/ for fixtures);
    • asks for the PR template's AI disclosure.
  • .gitignore: removes AGENTS.md. CLAUDE.md, GEMINI.md, .claude/ and .gemini/ stay ignored, so tool-specific files stay local.
  • CONTRIBUTING.md: adds the docblock rule under "General rules", so it applies to human contributors too, not only agents.

Testing Instructions

  1. Check that every link in AGENTS.md resolves, including CONTRIBUTING.md#documentation-standards.
  2. Check that each command in the Scripts block exists in package.json.
  3. Check that git status now shows a local AGENTS.md as tracked.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: reading the #307 and #308 discussion, checking the scripts and paths against the repo, and drafting the file and this description.

🤖 Generated with Claude Code

Open WordPress Playground Preview

@whyisjake @claude
Docs: add a minimal AGENTS.md
0c47c9a 
Adds a short AGENTS.md that points to CONTRIBUTING.md and the docs,
gives an abridged layout and the npm scripts, and sets two review
expectations: keep comments short, and test behavior rather than
wiring. Removes it from .gitignore, and adds the comment rule to
CONTRIBUTING.md so it applies to everyone.

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

codecov Bot commented Oct 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.25%. Comparing base (5bfb356) to head (0c47c9a).

Additional details and impacted files 
@@            Coverage Diff             @@
##             develop    #1195   +/-   ##
==========================================
  Coverage      82.25%   82.25%           
  Complexity      3403     3403           
==========================================
  Files            136      136           
  Lines          13225    13225           
==========================================
  Hits           10878    10878           
  Misses          2347     2347
Flag Coverage Δ
unit 82.25% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions

github-actions Bot commented Oct 15, 2026

Copy link
Copy Markdown

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

@justlevine

justlevine commented Oct 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Afterwards, @justlevine #307 (comment) the repo would be ready for "a minimal AGENTS.md (docs entrypoint, abridged directory tree, important scripts)".

(FWIW, that comment was made before the release of Claude "5" series model, whose recommended migration path was to delete everything, and rewrite from scratch. The current approach I recommend for cases like here is an AGENTS.example.md, so users can easily choose to use and adapt these files to their harness/models without having their context forcefully hijacked.
Edit: But I'm still not necessarily against. Worst case we revert it if it's causing problems. Just noting it seems first principles are still winning out.)

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@whyisjake @justlevine