Proposal: Add AGENTS.md for AI-assisted development

## Background

AI coding tools (Cursor, Copilot, Qoder, etc.) are becoming part of everyday development workflows. These tools rely on an `AGENTS.md` file in the repository root to understand project-specific context — build commands, conventions, debugging tips, and architectural decisions that aren't obvious from code alone.

Adding an `AGENTS.md` to Spring Cloud Alibaba will help community contributors use AI tools more effectively when submitting PRs, fixing bugs, and diagnosing issues.

## Proposal

Create and maintain an `AGENTS.md` at the repository root, built collaboratively by the community. Below are the proposed sections with example content to illustrate the expected depth and style.

### 1. Project Structure & Module Layout

Describe the high-level directory structure, what each top-level module is responsible for, and how modules relate to each other. This section should evolve as the project adds or removes modules.

**Example:**

> ```
> spring-cloud-alibaba/
> ├── spring-cloud-alibaba-starters/ # Core starter modules, one per component
> │ ├── spring-cloud-alibaba-commons/ # Shared utilities used by all starters
> │ ├── spring-alibaba-nacos-config/ # Nacos config core logic
> │ ├── spring-cloud-starter-alibaba-nacos-config/ # Starter that users depend on
> │ └── ...
> ├── spring-cloud-alibaba-tests/ # Integration tests (require external services)
> ├── spring-cloud-alibaba-examples/ # Runnable example applications
> ├── spring-cloud-alibaba-dependencies/ # BOM for dependency management
> └── spring-cloud-alibaba-coverage/ # JaCoCo coverage aggregation
> ```
>
> Key distinction: `spring-alibaba-nacos-config` contains core logic, while `spring-cloud-starter-alibaba-nacos-config` is the user-facing starter that depends on it. This pattern applies to other components as well.

### 2. Troubleshooting & Debugging

Per-component guidance on how to reproduce, test, and diagnose issues. Include pointers to example projects, test utilities, and diagnostic tools.

**Example:**

> For Nacos-related issues, use the example applications under `spring-cloud-alibaba-examples/nacos-example/` to reproduce the problem. To quickly spin up a Nacos server, use [nacos-setup](https://nacos.io/en/docs/latest/quickstart/quick-start/?spm=5238cd80.1f77ca18.0.0.1839e37ewKGNCY#21-one-click-deployment-with-nacos-setup-recommended) for one-click deployment. When the codebase lacks debug-level logging for a specific path, attach [Arthas](https://arthas.aliyun.com/) to the running process for runtime diagnostics.

### 3. Module Dependency & Impact Scope

Document which modules are affected when a specific module changes, so AI tools can determine the right scope for testing and validation.

**Example:**

> Changes to `spring-cloud-alibaba-commons` potentially affect **all** starter modules — always run a full build (`./mvnw clean install`) after modifying shared code. Changes to `spring-alibaba-nacos-config` require verifying behavior in `spring-cloud-starter-alibaba-nacos-config` as well.

### 4. Testing Strategy

Describe what level of testing is expected for different types of changes, and any external dependencies required.

**Example:**

> Integration tests under `spring-cloud-alibaba-tests/` require running external services (Nacos, RocketMQ, etc.). For local development, start the required service before running tests. Unit tests in each module's `src/test/java/` should not depend on external services.

### 5. Common Mistakes & Anti-Patterns

Capture recurring issues from community PRs so AI tools can avoid them proactively.

**Example:**

> - Do NOT hardcode version numbers in child module `pom.xml` files. The project uses `flatten-maven-plugin` with `${revision}` for CI-friendly versioning.
> - Checkstyle validation runs at the Maven `validate` phase. Always run `./mvnw compile` before pushing to catch violations early.

## How to Contribute

This is a community co-build effort. You can contribute by:

- Picking any section above and submitting a PR with detailed, experience-based content
- Adding new sections that you think would help AI tools understand this project better
- Improving existing examples with more specific commands, links, or workflows

All contributions should focus on **practical, actionable knowledge** — things that aren't obvious from reading the code or README alone.

**Note:** The sections above are just a rough reference, not the final structure. We welcome all community members to brainstorm, share ideas, and actively contribute to building this together.

Create the repository-root AGENTS.md and review the project structure, Maven commands, and testing guidance described in the issue. Use ./mvnw compile and ./mvnw clean install as the documented validation commands, and cover the proposed module layout, troubleshooting, impact scope, testing strategy, and common mistakes. Done means a practical, maintainable guide exists with actionable project-specific content.

Written by the indexing model from the issue text.