Skip to content

Commit 3895a23

Browse files
toxicity188toxicity188
authored
Merge pull request #279 from toxicity188/codex/analyze-project-structure-and-standards
Codex-generated pull request
2 parents 5455b18 + 5af5fb2 commit 3895a23

File tree

1 file changed

+235
-32
lines changed

1 file changed

+235
-32
lines changed

‎AGENTS.md‎

Lines changed: 235 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,245 @@
1-
# Overview
2-
This document defines the roles, responsibilities, and operational guidelines for AI agents interacting with the BetterModel repository. As a Modern Bedrock model engine for Minecraft Java Edition, maintaining technical precision and documentation integrity is paramount.
1+
# BetterModel AGENT GUIDE (for Codex, Gemini, and other LLM agents)
32

4-
## Agent Roles & Scopes
5-
* Documentation Specialist (Current Priority)
6-
Role: Maintains and expands Javadoc and Wiki content.
7-
```
8-
Responsibilities:
3+
This document defines repository-wide operating rules for automated contributors.
4+
Scope: entire repository unless a deeper AGENTS.md overrides this file.
95

10-
Generate comprehensive Javadoc for Kotlin/Java source files, focusing on public APIs.
6+
## 0) Mission and Priorities
117

12-
Maintain the GitHub Wiki and DeepWiki pages to reflect the latest engine features.
8+
- Primary mission: act as a maintenance assistant for safe updates and long-term stability.
9+
- Prioritize documentation quality, API clarity, and compatibility over refactoring.
10+
- Do not introduce architectural churn or speculative abstractions.
11+
- Prefer minimal, reversible changes that preserve current behavior.
1312

14-
Ensure all technical terms (e.g., Molang, Item Display, Packet-based rendering) are used consistently.
13+
---
1514

16-
Constraint: Do not alter functional logic or architectural patterns unless explicitly requested.
17-
```
18-
* Technical Architect (Contextual Support)
19-
Role: Analyzes the engine's core components for optimization and bug tracking.
15+
## 1) Module Responsibilities
2016

21-
### Focus Areas:
22-
- Model Processing: .bbmodel parsing and geometry extraction.
23-
- Animation Engine: Molang evaluation and 12-limb player animation syncing.
24-
- Rendering: Server-side packet handling via item_display entities.
17+
### MUST
18+
- Respect module boundaries:
19+
- `api`: architecture contracts, data definitions, pure logic, interfaces, domain exceptions.
20+
- `core`: implementation of `api`, orchestration, external I/O integration.
21+
- `platform/*`: platform packaging and platform-specific business integration using `core`.
22+
- `nms/*`: Minecraft-version-specific low-level adapters only.
23+
- Keep dependency direction one-way where possible: `api -> core -> platform/nms` usage semantics.
24+
- If a feature needs cross-module changes, start from `api` contract, then implement in `core`, then bind in `platform`.
2525

26-
## Task Guidelines
27-
Javadoc Standards
28-
### When generating Javadoc, agents must:
26+
### FORBIDDEN
27+
- Do not place platform/runtime-specific details in `api`.
28+
- Do not move business logic into `nms` unless version coupling is unavoidable.
29+
- Do not bypass module contracts with ad-hoc cross-module shortcuts.
2930

30-
- Explain the purpose of the class/method in the context of Minecraft server-side rendering.
31-
- Document `@param` and `@return` types, especially for complex types like MolangCompiler or DisplayEntity.
32-
- For Java Record classes, every component (field) must be documented using the `@param` tag.
33-
- Include `@since` tags corresponding to the current versioning in gradle.properties.
31+
---
3432

35-
### Git & Code Interaction
36-
Commit Messages: Use conventional commits (e.g., docs: add Javadoc for AnimationController).
37-
Non-Invasive Edits: Prioritize adding comments and documentation over refactoring stable code.
33+
## 2) Language and File Placement Rules
3834

39-
## Reference Material
40-
- README.md: Core engine features and build info.
41-
- DeepWiki: Advanced usage and API examples.
42-
- Dependencies: Refer to Gradle files to understand the library ecosystem (Caffeine, Molang, Cloud, etc.).
35+
### MUST
36+
- Use Modern Java (language level 21) and Kotlin.
37+
- `api` module is Java-only for production code (Kotlin DSL build scripts are allowed).
38+
- Non-`api` modules should be Kotlin-first unless existing local code is explicitly Java-bound (e.g., mixin/accessor interop).
39+
- Follow existing package root `kr.toxicity.model...` and module-specific suffixes.
40+
41+
### FORBIDDEN
42+
- Do not add Kotlin source files to `api/src/main`.
43+
- Do not introduce new language stacks or code generators without explicit request.
44+
45+
---
46+
47+
## 3) Allowed vs Forbidden Change Rules
48+
49+
### MUST
50+
- Preserve existing behavior unless the task explicitly requests behavior change.
51+
- Match local style of touched files (imports, naming, nullability annotations, formatting).
52+
- Keep diffs small and scoped to the requested issue.
53+
- Update/extend Javadoc when touching public Java APIs.
54+
55+
### RECOMMENDED
56+
- Prefer additive changes over invasive rewrites.
57+
- Prefer extension/composition over inheritance.
58+
59+
### FORBIDDEN
60+
- No drive-by refactors.
61+
- No broad renaming/reformatting-only commits mixed with functional changes.
62+
- No “cleanup” changes unrelated to the requested task.
63+
64+
---
65+
66+
## 4) Code Patterns and Conventions
67+
68+
### Java rules
69+
70+
#### MUST
71+
- Add English Javadoc for public API types/methods.
72+
- Use `var` for local variables where legal and clear.
73+
- When using primitive-key/value collections, prefer fastutil specialized types over boxed `java.util` alternatives.
74+
- Declare classes `final` when inheritance is not intended.
75+
- Use `of(...)` for factory method naming.
76+
- Prefer enum-based singleton pattern when a singleton is required.
77+
78+
#### RECOMMENDED
79+
- Prefer `record` for immutable data carriers.
80+
- Interface-based API should expose its own factory method where practical.
81+
82+
#### DISCOURAGED
83+
- Inheritance-heavy designs.
84+
85+
#### FORBIDDEN
86+
- Do not depend on Kotlin classes from Java in `api`.
87+
88+
### Kotlin rules
89+
90+
#### MUST
91+
- For Boolean arguments in calls, use named arguments (`parameter = value`) where available.
92+
- Keep Kotlin style concise and explicit; avoid hidden side effects.
93+
94+
#### RECOMMENDED
95+
- Avoid `abstract class` when interface + default methods or delegation works.
96+
97+
#### FORBIDDEN
98+
- No Kotlin production code in `api` module.
99+
100+
---
101+
102+
## 5) Javadoc Policy
103+
104+
### MUST
105+
- English only.
106+
- Use `@since` matching current `gradle.properties` project version policy.
107+
- Include `@return` for non-void methods.
108+
- For records, document all components using `@param` at type level.
109+
- Include `@throws` for throw-capable public methods.
110+
- Public API docs must include a usage example (`@example` or code block).
111+
- Keep terminology consistent with project domain (Molang, item_display, packet-based rendering, etc.).
112+
113+
---
114+
115+
## 6) Exception Handling Policy
116+
117+
### MUST
118+
- Domain exceptions must be declared in `api` and reused by `core/platform`.
119+
- Use unchecked exceptions for domain errors (`RuntimeException` subclasses).
120+
- Prefer explicit domain exception types over anonymous `RuntimeException` for new logic.
121+
122+
### FORBIDDEN
123+
- No new checked exceptions in public API surface unless explicitly requested.
124+
- No swallowing exceptions without logging/context.
125+
126+
---
127+
128+
## 7) Architectural Boundary Enforcement
129+
130+
### MUST
131+
- Enforce separation of concerns:
132+
- parsing/model contracts in `api`
133+
- orchestration and state management in `core`
134+
- runtime platform hooks in `platform`
135+
- protocol/version internals in `nms`
136+
- Keep NMS version modules behaviorally equivalent unless version-specific differences are required.
137+
138+
### FORBIDDEN
139+
- Do not leak platform classes into generic API contracts.
140+
- Do not duplicate core logic in multiple platform modules.
141+
142+
---
143+
144+
## 8) Change Management Principles
145+
146+
### MUST
147+
- Before coding, identify smallest viable patch.
148+
- Keep commits logically atomic.
149+
- Use conventional commits (`docs:`, `fix:`, `refactor:`, `chore:`).
150+
- Document why a change is necessary, not only what changed.
151+
152+
### RECOMMENDED
153+
- Prefer one concern per PR.
154+
- If migration is unavoidable, provide transitional compatibility notes.
155+
156+
---
157+
158+
## 9) Minimal Change Principle (Anti-Overengineering)
159+
160+
### MUST
161+
- Solve the concrete problem only.
162+
- Reuse existing utilities/conventions before introducing new abstractions.
163+
- Avoid framework-like internal layers unless repeatedly justified by current code.
164+
165+
### FORBIDDEN
166+
- No speculative extensibility.
167+
- No premature optimization without evidence.
168+
169+
---
170+
171+
## 10) Backward Compatibility Policy
172+
173+
### MUST
174+
- Preserve existing public API behavior by default.
175+
- Treat changes to signatures, semantics, serialization shape, config keys, and command contracts as breaking.
176+
- For unavoidable breaking changes: document impact, migration path, and versioning intent.
177+
178+
### RECOMMENDED
179+
- Prefer deprecation + transition period over hard removal.
180+
181+
---
182+
183+
## 11) Dependency Introduction Policy
184+
185+
### MUST
186+
- Prefer existing dependencies and in-repo utilities.
187+
- Any new dependency requires clear justification: purpose, scope, size, and maintenance cost.
188+
- Add dependency versions through central version catalog/patterns already in use.
189+
190+
### FORBIDDEN
191+
- Do not add dependencies for trivial utilities already present in JDK/Kotlin stdlib/current stack.
192+
- Do not introduce overlapping libraries providing the same capability.
193+
194+
---
195+
196+
## 12) Diff and PR Format Guidelines
197+
198+
### MUST
199+
- Keep PRs reviewable: focused scope, clear title, concise rationale.
200+
- Include:
201+
- summary of changes
202+
- impacted modules
203+
- compatibility notes
204+
- tests/checks run
205+
- Separate mechanical formatting from logic changes whenever possible.
206+
207+
### RECOMMENDED
208+
- Use checklist format for validation and risk points.
209+
210+
---
211+
212+
## 13) Test Policy
213+
214+
### MUST
215+
- Run the most relevant checks for touched modules.
216+
- Validate both compile-time and behavior-level impact where feasible.
217+
- If tests are absent, run targeted build/lint/verification tasks and report limitations.
218+
219+
### RECOMMENDED
220+
- Prefer adding focused tests only when directly related to changed behavior.
221+
- Keep test fixtures lightweight; do not add broad test frameworks without request.
222+
223+
---
224+
225+
## 14) Existing Code Precedence Rule
226+
227+
### MUST
228+
- Existing local code patterns take precedence over generic best practices when conflicts arise.
229+
- Follow deeper-scope AGENTS.md if present.
230+
- If repository reality conflicts with this guide, preserve behavior first and propose policy alignment separately.
231+
232+
### FORBIDDEN
233+
- Do not force style unification across untouched files.
234+
235+
---
236+
237+
## 15) Final Operational Checklist
238+
239+
Before finishing, verify:
240+
- Scope is minimal and task-aligned.
241+
- Module boundaries are respected.
242+
- Public API docs are updated (if touched).
243+
- Exception policy and compatibility policy are respected.
244+
- Changes are validated with relevant checks.
245+
- PR description contains rationale, risks, and verification results.

0 commit comments

Comments
 (0)