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.