feat: Create a basic AGENTS.md file for LLMS

[martyngigg]

Summary

Create an AGENTS.md file. Uses some examples:

• https://github.com/apache/airflow/blob/main/AGENTS.md
• https://github.com/apache/superset/blob/master/AGENTS.md

Preferred AGENTS.md over LLMS.md as it is a more commonly used format, e.g. in tools like CodeRabbit.ai

Fixes #154

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide documentation covering repository overview, development setup, testing procedures, deployment guidance, contribution standards, and troubleshooting resources.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

A single documentation file AGENTS.md has been added, serving as an LLM Context Guide for the Analytics Data Platform. It covers repository structure, development procedures, testing, deployment, and troubleshooting without containing executable code.

Changes

Cohort / File(s)	Summary
LLM Context Documentation AGENTS.md	New documentation file providing a comprehensive guide for LLM tools. Contains sections on repository purpose, layout, pre-commit hooks, unit and e2e testing with elt-common, Docker/infrastructure setup, cloud deployment, PR guidelines, troubleshooting, and next steps.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• No logic changes or functional code modifications to review
• Pure documentation addition with straightforward content structure
• No executable code paths, configurations, or test updates affected

Poem

🐰 A guide for our digital friends so bright,
AGENTS.md shines with knowledge and light,
Developers and bots, now hand in paw,
Through repositories they'll hop without flaw,
Documentation complete—no more mystery to chew! 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "feat: Create a basic AGENTS.md file for LLMS" accurately summarises the main change in the changeset. The title clearly conveys that the PR adds a new AGENTS.md documentation file to support LLM tools. It is concise, specific, and uses the conventional "feat:" prefix to indicate a feature addition. A teammate reviewing the repository history would immediately understand that this change introduces an LLM context guide file for the repository.
Linked Issues Check	✅ Passed	The pull request successfully addresses the core objective of linked issue #154, which requests an LLM context file (specified as "LLMS.md or equivalent") to enable CodeRabbit support. The PR adds an AGENTS.md file instead of LLMS.md, which the PR description justifies as a more commonly used format that is better supported by CodeRabbit and other tools. The file contains a concise LLM context guide documenting repository purpose, layout, development instructions, and troubleshooting guidance—precisely the information needed to support LLM tools in understanding the repository. This alternative approach fulfils the intent of issue #154 while using a more appropriate format.
Out of Scope Changes Check	✅ Passed	The pull request contains only the addition of AGENTS.md, a new documentation file serving as an LLM context guide. The raw summary confirms this contains "no executable code or functional changes" and covers repository documentation directly aligned with the objective of linked issue #154. No extraneous changes are evident, such as modifications to existing files, code refactoring, or unrelated updates. All changes presented are directly in scope and purposefully address the linked issue requirement.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between ca5a417 and 03be07f.

📒 Files selected for processing (1)

• AGENTS.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

AGENTS.md

[uncategorized] ~3-~3: Possible missing comma found.
Context: ...ains ELT code for an Iceberg-based data warehouse together with infrastructure code used ...

(AI_HYDRA_LEO_MISSING_COMMA)

---

[grammar] ~38-~38: Possible agreement error. Did you mean “units”?
Context: ...l. ## Running tests - There are both unit and e2e tests for the elt-common` pack...

(THERE_RE_MANY)

---

[uncategorized] ~40-~40: The abbreviation “e.g.” (= for example) requires two periods.
Context: ...v dependencies in a Python environment, e.g with uv ```bash cd elt-common/ uv ve...

(E_G)

---

[uncategorized] ~75-~75: The official name of this software platform is spelled with a capital “H”.
Context: ...the current PR template**: Always check .github/PULL_REQUEST_TEMPLATE.md for the lates...

(GITHUB)

---

[uncategorized] ~81-~81: The official name of this software platform is spelled with a capital “H”.
Context: ...s reference the actual template file at .github/PULL_REQUEST_TEMPLATE.md instead of us...

(GITHUB)

🔇 Additional comments (1)

AGENTS.md (1)

1-100: Document structure and coverage look good.

This LLM Context Guide provides excellent orientation for both developers and LLM-based agents. The sections are well-organised, covering repository layout, development workflows, testing procedures, deployment, and PR conventions. The practical examples and clear instructions are valuable for onboarding and assisting agents. Once the minor text corrections above are addressed, this should serve the project well.