Skip to content

docs(agents): AGENTS.md canonical + docs-vs-code precedence rule - #62

Merged
yu-iskw merged 1 commit into
mainfrom
cursor/docs-agents-md-canonical-4dc6
Oct 25, 2026
Merged

yu-iskw merged 1 commit into
mainfrom
cursor/docs-agents-md-canonical-4dc6

Conversation

@yu-iskw

@yu-iskw yu-iskw commented Oct 25, 2026

Copy link
Copy Markdown
Owner

Summary

Documentation-only change for coding agents (context: arXiv 2610.30571, yu-iskw/TODO#304).

  • Add AGENTS.md as the canonical instruction file: project overview, verbatim “When documentation and code disagree” section, generated-client guardrails, and dev commands (each cited to its defining file).
  • Add CLAUDE.md as a thin shim (# CLAUDE.md, then @AGENTS.md) so Claude Code loads shared guidance.

No source, test, CI, dependency, or generated-file changes.

Files changed

File Change
AGENTS.md Created (38 lines)
CLAUDE.md Created (7 lines)

CLAUDE.md handling

Before Absent (no agent instruction files in repo)
After # CLAUDE.md H1, blank line, @AGENTS.md, HTML comment, empty ## Claude Code section (no Claude-only content existed to preserve)

Inconsistencies found

Audited AGENTS.md (new), README.md, Makefile, pyproject.toml, dev/setup.sh, dev/generate_clients.sh, dev/openapi-python-client.yml, .github/workflows/test.yml, and lightdash_client/__init__.py. No .cursor/rules, GEMINI.md, .github/copilot-instructions.md, .claude/settings.json, or docs/adr present.

Doc + section What code / config does Evidence Fixed?
Makefile build target runs lint before flit build CI workflow does not run pre-commit lint (step commented out) Makefile:42-43, .github/workflows/test.yml:35-37 reported
pyproject.toml [project.optional-dependencies] dev pins flit ==3.10.1 dev/setup.sh installs flit==3.9.0 before flit install pyproject.toml:65, dev/setup.sh:24-25 reported
dev/openapi-python-client.yml package_version_override: 0.2.0 Published import version is lightdash_client.__version__ == "0.1471.0" dev/openapi-python-client.yml:6, lightdash_client/__init__.py:10 reported
Makefile several targets use .PHONE GNU Make only treats .PHONY as phony; .PHONE is not special Makefile:22, Makefile:37 reported

Uncertainties

  • Whether lightdash_client/__init__.py __version__ is intentionally maintained outside the openapi-python-client generator (it is not overwritten by dev/generate_clients.sh rsync).
  • Cursor precedence of root AGENTS.md vs hypothetical future .cursor/rules is not documented by Cursor; not applicable today (no project rules).

Local checks

  • pre-commit run --files AGENTS.md CLAUDE.md — passed (EOF, trailing whitespace, ruff hooks).
  • bash dev/test_python.sh — passed (1 test).
Open in Web Open in Cursor 

Add canonical agent instructions with docs-vs-code precedence rule,
generated-code guardrails, and verified dev commands. CLAUDE.md imports
AGENTS.md per Claude Code shim pattern.

Co-authored-by: Yu Ishikawa <yu-iskw@users.noreply.github.com>
@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Caution

Review failed

The pull request is closed.

Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@yu-iskw
yu-iskw marked this pull request as ready for review October 25, 2026 07:32
@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

@yu-iskw
yu-iskw merged commit b889100 into main Oct 25, 2026
6 of 7 checks passed
@yu-iskw
yu-iskw deleted the cursor/docs-agents-md-canonical-4dc6 branch October 25, 2026 07:33
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