Skip to content

AGENTS.md

Latest commit

 

History

History
450 lines (382 loc) · 23.5 KB

AGENTS.md

File metadata and controls

450 lines (382 loc) · 23.5 KB

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working with the Nacos repository. For human contributors, see CONTRIBUTING.md.

AI Contribution Guidelines

  • Do NOT post AI-generated comments on issues or PRs. Discussions are for humans only.
  • Discuss before implementing: Ensure the implementation direction is agreed upon with maintainers in the issue comments before starting work.
  • Spec-first coding is mandatory: Before changing behavior, APIs, SDKs, plugins, storage, runtime flow, or domain semantics, AI agents MUST read the relevant specs under specs/ and treat them as the rule source for the implementation.
  • Discuss spec-impacting changes before coding: If a change touches behavior covered by an existing spec, or exposes a gap between the code and the spec, AI agents MUST discuss the implementation direction and the required spec update with maintainers before starting the code change.
  • Update specs with the design: Any design proposal that changes or clarifies spec-covered behavior MUST include the corresponding spec updates in the same change set. When the design is large or controversial, prefer a spec/design-only PR first, then follow with implementation PRs.
  • API IT impact comes first: Before adding, changing, deleting, or deprecating any HTTP API, AI agents MUST analyze the affected test/openapi-test coverage and update the API IT scenario matrix, test cases, and coverage registry in the same change set. If the functional path cannot be exercised in standalone IT, cover boundary/error scenarios and document the reason.
  • Java SDK IT impact comes first: Before adding, changing, deleting, or deprecating any public Java SDK interface, factory, model, listener behavior, lifecycle behavior, or exception mapping, AI agents MUST analyze and update test/java-sdk-test coverage, including scenario documentation. If the end-to-end success path is impractical, cover SDK parameter validation, boundary behavior, and controlled exceptions.
  • Disclose AI usage: When a significant part of a commit is AI-generated, add a trailer to your commit message: 
    Assisted-by: Claude Code
  • Follow CONTRIBUTING.md for all contribution processes.

Repository Overview

Nacos (Dynamic Naming and Configuration Service) is an easy-to-use platform designed for dynamic service discovery, configuration management, and AI agent management. It helps you build cloud-native applications and AI Agent applications easily. Key capabilities: service discovery, dynamic configuration, dynamic DNS service, service/metadata management, and AI registry (Prompt, MCP, A2A).

Current Version: 3.2.1-SNAPSHOT | Main Branch: develop | Java: JDK 17+ (client modules: JDK 8+) | Build: Maven 3.2.5+

Core Architecture

Key modules and their roles:

  • api / client / client-basic: Client-facing APIs, gRPC definitions, SDK (Java 8 compatible)
  • common: Shared utilities, HTTP client, notify center, executor
  • config: Configuration management server
  • naming: Service discovery and registration server
  • core: Core server infrastructure (cluster, distributed consensus)
  • consistency: JRaft-based CP protocol + custom Distro AP protocol
  • auth: Authentication and authorization
  • plugin / plugin-default-impl: Extensible plugin system (Java SPI). Types: auth, visibility, datasource dialect, config change, encryption, trace, environment, control, AI pipeline, AI storage
  • console / console-ui: Web UI backend (Spring Boot) and frontend (React)
  • ai / copilot / ai-registry-adaptor: AI Agent support, Copilot integration, and AI registry adaptor
  • sys: System environment utilities and JVM parameter management
  • bootstrap / server: Server startup and aggregation
  • persistence: Data persistence with multi-database support (Derby, MySQL, PostgreSQL)
  • maintainer-client: Internal maintenance client
  • lock: Distributed lock support

Communication: gRPC (primary) + HTTP/REST (legacy compatibility). Protobuf definitions in api/src/main/proto/.

Build & Test Commands

# Full build (skip tests)
mvn '-Prelease-nacos,!dev' -Dmaven.test.skip=true clean install -U

# Run all unit tests
mvn test

# Run standalone-server integration tests
mvn -pl test/openapi-test -Pintegration-test -DskipTests=false verify
mvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false verify
mvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTests=false verify

# Format code (run before commit)
mvn spotless:apply

# Pre-submission checks (MUST pass before PR)
mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests

Mandatory Formatting Before Commit

Before committing Java code or tests, AI agents MUST run Spotless for the affected module or nearest aggregator:

  1. Run mvn spotless:apply first.
  2. Run mvn spotless:check for the same scope.
  3. Then run the relevant compile/check/test command.
  4. Commit only after Spotless and the relevant validation pass.

Do not rely on checkstyle:check, spotbugs:check, or git diff --check as a substitute for Spotless. Spotless uses the project formatter and may accept formatting that generic whitespace checks report differently.

Code Style

Follows Alibaba Java Coding Guidelines.

Key Rules for AI Agents

Rule Value
Indentation 4 spaces (basic offset), 4 spaces (case indent)
Line length 100 characters max (enforced by Spotless + Checkstyle)
Star imports Forbidden — always use explicit imports
Unused imports Forbidden
Javadoc Required for API methods (exemptions: @Override, @Test, @Before, @After, @BeforeClass, @AfterClass, @Parameterized, @Parameters, @Bean)
Braces Required for all if/else/for/while/do-while blocks, even single-line
Switch Must have default case; fall-through must be commented
Naming camelCase for methods/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants
Abbreviations Max 1 consecutive capital letter in names (exception: VO)

License Header

Every new source file must include the Apache License 2.0 header. CI enforces this via apache-rat:check.

/*
 * Copyright 1999-${year} Alibaba Group Holding Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

API Standards

Nacos v3 APIs follow strict conventions. AI agents must comply with these standards when generating controller code.

Authoritative API and SDK specs live under specs/. Before coding any API, SDK, plugin, storage, runtime, or domain change, AI agents MUST consult the relevant specs below. If the intended behavior differs from the existing spec, do not silently implement the code first: discuss the change with maintainers and update the affected specs as part of the design. For broad or uncertain changes, submit a spec/design PR first so the contract is reviewed before implementation.

English:

Simplified Chinese:

This section is a quick implementation checklist for agents. If it conflicts with the specs, follow the specs and update this checklist.

URL Path Patterns

API Type Base Path Purpose Example
Open API /v3/client/{module}/... Client-facing operations /v3/client/ns/instance
Admin API /v3/admin/{module}/... Administrative operations /v3/admin/ns/service
Console API /v3/console/{module}/... Web console operations /v3/console/cs/config
Auth API /v3/auth/{resource}/... Plugin-provided auth operations /v3/auth/user

Module Names

Module Abbreviation Scope
Config Service cs Configuration management
Naming Service ns Service discovery
Core core Cluster, namespace management
AI ai AI resource management
Plugin plugin Plugin management

Note: Auth APIs (/v3/auth/user, /v3/auth/role, /v3/auth/permission) are defined in plugin-default-impl module, not in core.

HTTP Method Semantics

Method Usage Idempotent
GET Query / Retrieve Yes
POST Create / Register No
PUT Update / Modify Yes
DELETE Remove / Deregister Yes

Response Format

Always wrap responses in com.alibaba.nacos.api.model.v2.Result<T>:

{
  "code": 0,
  "message": "success",
  "data": { }
}

Authentication

Always add @Secured annotation (com.alibaba.nacos.auth.annotation.Secured):

@Secured(action = ActionTypes.READ,       // READ or WRITE
         signType = SignType.CONFIG,       // CONFIG, NAMING, or CONSOLE
         apiType = ApiType.ADMIN_API)      // OPEN_API, ADMIN_API, or CONSOLE_API

API Integration Tests

For every HTTP API addition, modification, deletion, or deprecation, handle test/openapi-test before the API change is considered complete:

  1. Read the affected controller, form/request model, validators, service path, response model, exception handling, and matching specs.
  2. Build or update the scenario matrix for expected capability, boundary/validation behavior, and exception/error handling.
  3. Add, update, or remove API IT cases for the changed contract. The goal is API scenario coverage, not line or branch coverage.
  4. Update test/openapi-test/API_TEST_COVERAGE.md and the matching *_API_TEST_SCENARIOS.md document.
  5. If the functional success path is hard to exercise in standalone IT, at least cover boundary and error scenarios and document the uncovered path.

Java SDK Integration Tests

For every Java SDK public contract change, handle test/java-sdk-test before the SDK change is considered complete:

  1. Read the public interface, implementation, request/response model, listener path, lifecycle code, exception mapping, and matching SDK/client specs.
  2. Build or update the scenario matrix for factory/lifecycle behavior, expected capability, boundary/validation behavior, listener/subscription behavior, and exception handling.
  3. Add, update, or remove Java SDK IT cases for the changed SDK contract. Assert SDK return values, callbacks, remote side effects, and typed exceptions.
  4. Update test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md.
  5. Keep SDK ITs as external-client tests against a standalone Nacos server; do not start Spring or Nacos inside the test class.

Controller Example

import com.alibaba.nacos.api.model.v2.Result;
import com.alibaba.nacos.auth.annotation.Secured;
import com.alibaba.nacos.plugin.auth.constant.ActionTypes;
import com.alibaba.nacos.plugin.auth.constant.SignType;
import com.alibaba.nacos.api.common.ApiType;

@RestController
@RequestMapping("/v3/admin/ns/service")
public class ServiceControllerV3 {

    @PostMapping
    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)
    public Result<String> create(ServiceForm serviceForm) throws Exception {
        serviceForm.validate();
        // business logic ...
        return Result.success("ok");
    }

    @GetMapping("/list")
    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)
    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {
        serviceListForm.validate();
        // business logic ...
        return Result.success(result);
    }
}

Java Version Targeting

  • Server modules (config, naming, core, console, etc.): Java 17+
  • Client/API/Plugin modules (api, client, plugin): Java 8+ — ensure backwards compatibility when modifying

PR Convention

All PRs must target the develop branch. Follow the PR template.

Title format: [ISSUE #14122] Add JVM --add-opens options for JDK 17+ compatibility

Pre-submission checklist:

mvn -B clean package apache-rat:check spotbugs:check -DskipTests
mvn clean install
mvn clean test-compile failsafe:integration-test

Security Vulnerabilities

Do NOT report security vulnerabilities via GitHub Issues. Use ASRC (Alibaba Security Response Center) instead.