# Agent Guidelines for cluster-service-ng

## OVERVIEW

TiDB Cloud Cluster Service is the regional control-plane service for TiDB cluster lifecycle. Business workflows live here; infrastructure changes go through Dataplane Manager.

This file is a map, not an encyclopedia.

→ **Start here**: [`ARCHITECTURE.md`](ARCHITECTURE.md)  
→ **Cross-service work**: [`internal/AGENTS.md`](internal/AGENTS.md)

## STRUCTURE

```text
cluster-service-ng/
├── cmd/                    # Entry points
│   ├── cluster_ng_server/  # Main service
│   ├── executor/           # Background task executor
│   └── autoscale_stub/     # Auto-scaling stub
├── domain/                 # Business logic
│   ├── server/             # gRPC handlers
│   ├── workflow/           # DAG workflows
│   ├── entity/             # Domain entity aliases
│   └── app/                # Application services and cron jobs
├── pkg/                    # Shared libraries
│   ├── storage/            # MySQL, etcd, repositories
│   ├── dataplane/          # Dataplane Manager client
│   └── tioperator/         # TiDB Operator integration
├── api/                    # Proto definitions (separate go.mod)
└── internal/               # Independent services (each has its own go.mod)
```

## WHERE TO LOOK

| Task | Location | Guide |
|------|----------|-------|
| Add gRPC endpoint | `domain/server/*.go` | [`ARCHITECTURE.md` → Protobuf / gRPC](ARCHITECTURE.md#protobuf--grpc) |
| Add workflow action | `domain/workflow/action/*.go` | [`ARCHITECTURE.md` → Workflow System](ARCHITECTURE.md#workflow-system) |
| Add database table or migration | `pkg/storage/mysql/schema/` | [`ARCHITECTURE.md` → Database](ARCHITECTURE.md#database) |
| Add proto API | `api/cluster-service-ng/v1beta/` | Run `make proto` |
| Add cron job | `domain/app/cron/` | [`ARCHITECTURE.md` → Cron Jobs](ARCHITECTURE.md#cron-jobs) |
| Add K8s CR template | `deployments/templates/` | [`ARCHITECTURE.md` → Template System](ARCHITECTURE.md#template-system) |
| Write lint-safe Go changes | — | [`ARCHITECTURE.md` → Conventions](ARCHITECTURE.md#conventions) |
| Trace domain invariants | — | [`ARCHITECTURE.md` → Critical Patterns](ARCHITECTURE.md#critical-patterns) |
| Follow internal service calls | `pkg/dataplane/`, `internal/` | [`internal/AGENTS.md`](internal/AGENTS.md) |

## COMMANDS

Select checks for the affected module and behavior; this is a command reference, not a checklist. Root build/test targets do not cover separate `internal/` modules. Run generators only when their source inputs change.

`make dev` tidies dependencies, applies lint fixes, regenerates files, builds, and tests. `make fmt` applies lint fixes; neither is a read-only check.

```bash
make dev
make build
make build-server
make test
make proto
make generate
make manifests
make generate-mocks
make lint
make fmt
```

## QUICK GUARDRAILS

- Add new shared protobuf types to `domain/entity/entity.go` first, then use `entity.*` across repo/service/server boundaries.
- The main Cluster Service's infrastructure operations go through `pkg/dataplane/`. Independent `internal/` services use Kubernetes clients according to their own responsibilities and local guidance.
- `UpdateNodePool` is replace-style; preserve existing labels unless you intend to rewrite them.
- Fallback creation is sequential; wait for the current fallback to be Ready before creating the next one.
- Follow surrounding test style: table-driven tests, `repomocks` for repo mocks.

## INTERNAL SERVICES

- `internal/` services are separate Go modules with separate build and test flows.
- Start with [`internal/AGENTS.md`](internal/AGENTS.md) for routing.
- For Dataplane Manager work, continue to [`internal/dataplane-manager/AGENTS.md`](internal/dataplane-manager/AGENTS.md).

## KNOWLEDGE BASE

| Document | Purpose |
|----------|---------|
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Deployment, data model, conventions, workflow, database, templates, protobuf |
| [`internal/AGENTS.md`](internal/AGENTS.md) | Map of independent services under `internal/` |
| [`docs/design/local-dev-design.md`](docs/design/local-dev-design.md) | Local development design |
| [`docs/design/node-instance-group-management.md`](docs/design/node-instance-group-management.md) | Node instance group management |
| [`docs/design/tenant-aware-autoscale-policy-redesign.md`](docs/design/tenant-aware-autoscale-policy-redesign.md) | Tenant-aware autoscale policy redesign — global vs regional split |