# AGENTS.md

## Project

Single-module Maven Java 17 project for learning the Docker Java SDK (`com.github.docker-java`).
Package: `space.anyi.docker`. Entry point: `src/main/java/space/anyi/docker/QuickStart.java`.

## Build & Run

- `mvn compile` — compile
- `mvn test` — run tests (JUnit 5; no tests exist yet)
- `mvn package` — package (skip tests: `mvn package -DskipTests`)
- `mvn exec:java -Dexec.mainClass="space.anyi.docker.QuickStart"` — run the demo

No Maven wrapper; uses system Maven (3.9.15+) and Java 17+.

## Requirements

Docker daemon must be running for the application to work. The SDK connects to the local Docker socket by default.

## Tutorial Writing Guidelines

### Narrative Structure

Follow the storytelling style and pacing defined in `template.md`. Key conventions:

- **开篇引入**: 每个章节开头用一段简洁的背景或场景描述引入主题，不直接上代码。
- **概念铺垫**: 先用一两段文字解释概念和设计动机，再给出接口或源码。
- **代码演示**: 每个知识点配一个可运行的完整示例，代码后紧跟运行结果或现象解释。
- **思考/提问**: 在关键点设置思考环节，用 **思考：** 引导读者主动分析。
- **小结过渡**: 每小节末尾自然过渡到下一节，保持整体连贯性。

### Per-Point Workflow

每完成一个小知识点后：

1. **自审**: 检查代码能否编译、注释是否清晰、输出是否使用 log、示例是否完整。
2. **提交**: 将该点的改动提交到本地 Git 仓库，commit message 简明描述该知识点（如 `feat: add ReentrantLock basics`）。
3. **继续下一个知识点**，循环直到章节完成。

### Code Standards

- **日志输出**: 代码中的信息输出统一使用 SLF4J Logger（项目已引入 logback-classic），禁止 `System.out.println`。
  - 声明: `private static final Logger log = LoggerFactory.getLogger(ClassName.class);`
  - 使用: `log.info(...)`, `log.debug(...)`, `log.warn(...)`, `log.error(...)`
- **注释**: 每个代码案例需有合理注释，说明关键步骤和设计意图，但不要过度注释（如逐行解释语法）。
- **测试**: 所有测试使用 JUnit 5 (`org.junit.jupiter.api`)，测试类放在 `src/test/java/space/anyi/docker/` 下，命名 `*Test.java`。
- **代码风格**: 保持与现有代码一致的风格，遵循 Java 17 语法。