AGENTS.md

1# Java Design Patterns - Priming Context for AI Agents
2 
3## Quick Overview
4- This repository is a comprehensive collection of design patterns implemented in Java.
5- The project demonstrates how to solve common software design problems using standard patterns.
6- The code for each pattern lives directly in this repository, alongside its explanatory README.
7- These readmes are published on the java-design-patterns.com website.
8- Another repository (https://github.com/iluwatar/java-design-patterns-vuepress-web) handles the deployment of the website.
9 
10## Stack
11- **Java 21**: The primary programming language used for pattern implementations.
12- **Maven**: Dependency management and build tool.
13- **JUnit 5**: The testing framework used to verify pattern behaviors.
14- **Mockito**: Used for mocking dependencies in unit tests.
15- **Lombok**: Used to reduce boilerplate code (getters, setters, etc.).
16- **Spotless**: Enforces consistent code formatting via Google Java Format.
17 
18## Trusted Sources
19- [Java SE 21 Documentation](https://docs.oracle.com/en/java/javase/21/docs/api/)
20- [Maven Official Documentation](https://maven.apache.org/guides/index.html)
21- [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/)
22- [Project Wiki](https://github.com/iluwatar/java-design-patterns/wiki)
23 
24## Structure
25- `/pom.xml`: The root Maven configuration file that defines global dependencies and lists all pattern modules.
26- `/[pattern-name]/`: Individual folders for each design pattern (e.g., `/abstract-factory`, `/builder`), acting as standalone Maven modules.
27- `/[pattern-name]/src/main/java/`: Contains the actual Java implementation classes of the specific design pattern.
28- `/[pattern-name]/src/test/java/`: Contains the JUnit tests verifying the pattern's behavior.
29- `/[pattern-name]/README.md`: The documentation for the pattern, which gets published to the main website.
30 
31## Patterns
32- Keep pattern implementations simple, atomic, and easy to understand.
33- Write descriptive and meaningful names for classes, interfaces, and methods.
34- Always include comprehensive unit tests for every new pattern or code modification.
35- Follow the Google Java Format strictly (enforced by Spotless).
36- Document the intent, explanation, and real-world usage clearly in each module's `README.md`.
37 
38## Anti-patterns
39- Avoid overcomplicating patterns with unnecessary external dependencies or complex frameworks.
40- Do not introduce business logic that distracts from the core mechanism of the design pattern itself.
41- Submitting new patterns or features without corresponding unit tests is strictly discouraged.
42- Avoid large monolithic packages; each pattern should reside in its own isolated module.
43 
44## Example Design Pattern
45When a new design pattern is added to the repository, it generally follows these steps:
46- **Create a Module**: Create a new folder for the pattern in the root directory (e.g., `/my-new-pattern`).
47- **Update root pom.xml**: Add `<module>my-new-pattern</module>` to the `<modules>` section of the root `pom.xml`.
48- **Add Module pom.xml**: Create a `pom.xml` inside the new folder that inherits from the parent project.
49- **Write the Code**: Implement the pattern logic under `src/main/java/com/iluwatar/mynewpattern`, usually including an `App.java` class to demonstrate its usage.
50- **Write the Tests**: Add comprehensive unit tests under `src/test/java/com/iluwatar/mynewpattern`.
51- **Document**: Create a `README.md` at the root of the new module, structured with standard sections like Intent, Explanation, Class diagram, Applicability, and Real world examples.
52