[#30272] YSQL: Add agent config files

Summary:
Adds a simple top-level [[ https://agents.md/ | AGENTS.md ]] file describing the layout of the repo.
Also, adds an AGENTS.md in `src/` describing how to build YugabyteDB, run tests, and run the linter.

This file lives in the `src/` directory, covering the postgres, YB C++, and Odyssey codebases.

Also adds a top-level AGENTS.md that for now just points to `src/AGENTS.md`, and a top-level `CLAUDE.md` that points to `AGENTS.md`.

Additionally, adds environment config files for Cursor cloud agents telling them to use the latest alma9 image from https://github.com/yugabyte/build-infra/tree/master/docker_images

Test Plan: Manual test: Create a Cursor cloud agent and have it run one of the DB unit tests, verify that the build + test succeeds

Reviewers: hsunder

Reviewed By: hsunder

Differential Revision: https://phorge.dev.yugabyte.com/D50343

Author: kai-franz

.cursor/Dockerfile

@@ -0,0 +1 @@
+FROM yugabyteci/yb_build_infra_almalinux9_x86_64:latest

.cursor/environment.json

@@ -0,0 +1,5 @@
+{
+    "build": {
+        "dockerfile": "Dockerfile"
+    }
+}

AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+This document provides a guide for agents working on YugabyteDB
+
+### Deploying and running
+
+For agents that want to deploy, configure and run YugabyteDB refer to instructions at https://docs.yugabyte.com/stable/quick-start
+
+### Repo Structure
+
+| Directory | What it contains |
+|---|---|
+| `src/` | Core database code: PostgreSQL fork (`src/postgres/`), YugabyteDB C++ storage engine (`src/yb/`), Odyssey connection pooler (`src/odyssey/`) |
+| `java/` | Java client library, CDC connector, and DB tests |
+| `managed/` | YugabyteDB Anywhere (YBA) platform — orchestration UI, CLI, node agent, and backend (Scala/Java) |
+| `docs/` | Source files for the docs website (docs.yugabyte.com) |
+| `python/` | Python build utilities and test infrastructure scripts |
+| `build-support/` | Build system scripts, linting, and third-party dependency tooling |
+| `cmake_modules/` | CMake modules for locating dependencies and custom build functions |
+| `cloud/` | Docker, Kubernetes, and Grafana deployment configurations |
+| `yugabyted-ui/` | Yugabyted web UI (React frontend + Go API server) |
+| `architecture/` | Internal design documents and architecture specs |
+| `troubleshoot/` | Troubleshooting framework backend and UI |
+
+### Coding and Development
+
+When working on DB code (`src/`), refer to `src/AGENTS.md` for build and test guidance

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -175,6 +175,8 @@ Review detailed architecture in our [Docs](https://docs.yugabyte.com/stable/arch
 
 As an open-source project with a strong focus on the user community, we welcome contributions as GitHub pull requests. See our [Contributor Guides](https://docs.yugabyte.com/stable/contribute/) to get going. Discussions and RFCs for features happen on the design discussions section of our [Forum](https://forum.yugabyte.com/c/design-discussions/7).
 
+For AI agents, refer to [AGENTS.md](AGENTS.md) for guidance on working with this codebase.
+
 # License
 
 Source code in this repository is variously licensed under the Apache License 2.0 and the Polyform Free Trial License 1.0.0. A copy of each license can be found in the [licenses](licenses) directory.

src/AGENTS.md

@@ -0,0 +1,38 @@
+## Build System
+
+The primary build entry point is `yb_build.sh` at the repository root.
+
+Use release build by default. Only use debug builds when explicitly asked to do so.
+Skip java build (`--sj`) unless you have to run java tests.
+
+The first time you run a test, you will need to run initdb beforehand:
+
+```bash
+./yb_build.sh release initdb
+```
+
+### Common Build Commands
+
+```bash
+./yb_build.sh release --sj
+```
+
+### C++ Tests
+
+```bash
+./yb_build.sh release --cxx-test tablet-test
+
+./yb_build.sh release --cxx-test cluster_balance_preferred_leader-test --gtest_filter TestLoadBalancerPreferredLeader.TestBalancingMultiPriorityWildcardLeaderPreference
+
+./yb_build.sh release --cxx-test cluster_balance_preferred_leader-test --gtest_filter "*Wildcard*"
+
+./yb_build.sh release --cxx-test cluster_balance_preferred_leader-test -n 10
+```
+
+### Java Tests
+
+```bash
+./yb_build.sh release --java-test org.yb.client.TestYBClient
+
+./yb_build.sh release --java-test 'org.yb.client.TestYBClient#testClientCreateDestroy'
+```