# AGENTS.md

## Project Overview

Java 17 / Maven tutorial project for JDK `CompletableFuture` API. Produces Chinese-language tutorial documents and accompanying code demos.

## Build & Run

```bash
mvn compile                                          # compile
mvn exec:java -Dexec.mainClass=space.anyi.Cf01_CreateStage   # run a demo (pick a Cf* class)
mvn test                                              # run tests (currently none)
```

- `exec:java` requires `-Dexec.mainClass` (the pom does not configure a default `mainClass`).
- In this environment `mvn` may not be on PATH. Use the IntelliJ-bundled Maven:
  `C:\Program Files\JetBrains\IntelliJ IDEA Community Edition 2023.3.8\plugins\maven\lib\maven3\bin`
- PowerShell splits unquoted `-Dexec.mainClass=...`; quote the argument: `'-Dexec.mainClass=space.anyi.Cf01_CreateStage'`.
- Console shows GBK encoding by default, so Chinese output may look garbled in terminal even though the program is correct.
- `exec:java` is unreliable for demos that use `orTimeout`/`completeOnTimeout` (e.g. `Cf10`): the JDK `CompletableFutureDelayScheduler` thread lingers and `exec-maven-plugin` reports a threadGroup teardown error even when the program is correct. Run such demos with plain Java instead: `& "C:\Program Files\Java\jdk-17\bin\java.exe" -cp target/classes space.anyi.Cf10_TimeoutAndException`.

No other build tools, linters, or formatters are configured.

## Structure

- `src/main/java/space/anyi/` — demo code (`Cf01`..`Cf10`, one file per API topic, each with a standalone `main()`)
- `completablefuture-tutorial.md` — tutorial doc (Chinese, follows `template.md` style)
- `completablefuture-blog.md` — blog/cheat-sheet doc for experienced Java programmers
- `template.md` — reference doc for writing style and structure (Chinese, covers JUC concurrency topics)
- `todo.md` — task list for outstanding work

## Conventions

- Follow the narrative structure and code-example style in `template.md` when writing new tutorial content.
- Package: `space.anyi`
- All tutorial prose is in Chinese.
- Code examples should be self-contained and runnable as standalone `main()` methods.
- Commit to the local git repository after completing each small task (e.g., each demo file, each document).