aidev
63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# AGENTS instructions for ta4j (root)
|
|
|
|
This file contains only repository-wide requirements.
|
|
If your framework already injected this file into context, do not spend extra tool calls reopening it repeatedly.
|
|
|
|
## 1) Completion gate (MUST)
|
|
Run the full verification script once when you have a candidate final patch:
|
|
|
|
- `scripts/run-full-build-quiet.sh`
|
|
|
|
You may skip this only when all changed files are exclusively within `.github/workflows/`, `CHANGELOG.md`, or documentation-only files (for example `*.md`, `docs/`).
|
|
|
|
Required outcome:
|
|
|
|
- Build is GREEN (`Failures: 0`, `Errors: 0`)
|
|
- Final report includes aggregated `Tests run / Failures / Errors / Skipped`
|
|
- Final report includes the log path emitted by the script (under `.agents/logs/`)
|
|
|
|
Do not rerun the full build after every edit. Use targeted tests while iterating, then run the full gate on the candidate final patch.
|
|
|
|
## 2) Fast feedback loop (SHOULD)
|
|
During implementation and debugging, prefer targeted test commands for speed (for example `mvn -pl ta4j-core test -Dtest=...`).
|
|
|
|
## 3) Test failure policy (MUST)
|
|
|
|
- Never ignore build or test failures.
|
|
- Never skip tests without explicit user approval.
|
|
|
|
## 4) Scoped AGENTS lookup (MUST)
|
|
Before editing a feature area, discover and follow all applicable scoped `AGENTS.md` files.
|
|
|
|
- Use `bash scripts/agents_for_target.sh <file-or-class>` to list path-scoped `AGENTS.md` guides for that target in precedence order from the current repo/workspace root.
|
|
- Deeper/closer `AGENTS.md` files override broader ones.
|
|
- Apply only instructions relevant to the path you are changing.
|
|
- This helper is only for path-scoped `AGENTS.md` discovery. Agents must still apply normal system, developer, user, and workflow-specific instructions independently, including any personal PR workflow guidance.
|
|
|
|
## 5) Process/worktree guidance
|
|
Worktree lifecycle and PRD/checklist process conventions live in `scripts/AGENTS.md`.
|
|
|
|
## 6) Reuse-first policy (MUST)
|
|
|
|
- Before adding a new type or API, search for existing equivalents and reuse them when possible.
|
|
- Do not introduce a new enum when an existing project enum already models the behavior.
|
|
- Prefer extending/adapting existing classes over creating parallel abstractions.
|
|
- If a new type is still required, document in the PRD/checklist or PR notes why existing types were insufficient.
|
|
- Reuse audit checkpoint: before introducing a new type, run a targeted code search for equivalent behavior and capture the reuse decision in 1-2 lines in PRD/checklist or PR notes.
|
|
|
|
## 7) Consolidation and API exposure (MUST)
|
|
|
|
- Consolidation-first helper rule: inline new logic into the owning type (private static methods or package-private nested helpers) before creating a new utility class.
|
|
- Only extract to a dedicated helper/utility class after at least two concrete call sites require shared behavior, or when testability/complexity clearly demands extraction.
|
|
- Readability-first helper rule: do not extract private helpers that are only 1-3 lines and used once unless the extracted name carries important domain meaning or materially simplifies a long method.
|
|
- When a tiny helper forces readers to jump around for one or two lines of logic, inline it back into the main flow.
|
|
- When stronger invariants already hold at the call site, prefer direct code over generic fallback helpers that obscure those invariants.
|
|
- New classes and methods should be package-private by default; treat public API additions as exceptional and require a short rationale in PRD/checklist or PR notes.
|
|
- Redundancy cleanup requirement: when new code overlaps existing behavior, remove or fold the redundant abstraction in the same change unless there is a documented blocker.
|
|
|
|
## 8) Local typing style (MUST)
|
|
|
|
- Prefer explicit local variable types.
|
|
- Use `var` only when the type is immediately and unambiguously obvious from the right-hand side.
|
|
- Do not use `var` for method-return values unless the type is trivial and fully clear from constructor/factory literal context.
|