<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you 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.
-->

# Gravitino Agent Guidelines

## General Coding Standards
- **Language**: Use English for all code, comments, and documentation.
- **Style**: Follow rigid Google Java Style. Run `./gradlew spotlessApply` to format.
- **Javadoc**: All new `public` and `protected` classes, methods, and fields must have Javadoc. Missing Javadoc fails the checkstyle CI step (runs with `-Werror`).
- **Imports**: Always use normal `import` statements instead of Fully Qualified Class Names (FQN) in Java code whenever possible.
  - **Bad**: `org.apache.gravitino.rel.Table table = ...;`
  - **Good**: `Table table = ...;` (with `import org.apache.gravitino.rel.Table;`)
  - Do not write inline types like `java.nio.file.Paths` or `org.apache.xxx.Table` unless there is a real class name conflict that cannot be resolved cleanly.
  - If two classes share the same simple name, prefer imports plus small refactors over keeping FQNs throughout the code.
- **Safety**: Use `@Nullable` annotations. Handle resources with try-with-resources.
- **Logging**: Use SLF4J. No `System.out.println`.
- **Testing**:
  - Write unit tests for ALL new logic. NO tests = NO merge.
  - Use `TestXxx` naming pattern (e.g., `TestCatalogService`).
  - Run tests: `./gradlew test -PskipITs`.
  - Docker tests: Tag with `@Tag("gravitino-docker-test")`; run them with `-PskipDockerTests=false`.
- **Class Member Ordering**: Follow the order:
  1. `static` constants (e.g., `LOG`).
  2. `static` fields.
  3. Instance fields.
  4. Constructors.
  5. Methods (Group by visibility, putting `private` methods at the end).

## Create Issue and PR Guidelines
[IMPORTANT] Before creating an issue or PR using the gh command or the GitHub MCP server, please show a preview of the PR/issue first. Submit it only after I confirm. The issue/PR format should follow the reference and keep the content concise and clear.
- **Issue Templates**: Use the appropriate template from `.github/ISSUE_TEMPLATE/`
- **PR Description**: Follow the template in `.github/PULL_REQUEST_TEMPLATE`

## Project Structure
- `api/`: Public interfaces.
- `common/`: Shared utilities/DTOs.
- `core/`: Main server logic.
- `server/`: REST API implementation.
- `catalogs/`: Catalog implementations (Hive, Iceberg, MySQL, etc.).
- `clients/`: Java/Python clients.

## Build Commands
- **Build**: `./gradlew build -PskipDockerTests=false`
- **Format**: `./gradlew spotlessApply`
- **Unit Tests**: `./gradlew test -PskipITs -PskipDockerTests=false`
- **Integration Tests**: `./gradlew test -PskipTests -PskipDockerTests=false`
- **OpenAPI Docs Validation**: `./gradlew :docs:build` — Run this after any changes to `docs/open-api/*.yaml` to validate OpenAPI specification correctness.

## Claude Memory Usage
- Before starting any task, use mcp-search to check if similar work has been done before.
  When encountering unfamiliar code or configuration, search memory for prior context.
- When hitting a problem, search memory first for known solutions before debugging from scratch.
- After completing a task, save key findings and solutions to claude-mem for future reference.
- Use multiple keyword combinations when searching (e.g., module name + issue type, class name + error).
