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 for one-click deployment. When the codebase lacks debug-level logging for a specific path, attach Arthas 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.