61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
|
# AGENTS.md
|
||
|
|
|
||
|
|
## Planning and Spec Source of Truth
|
||
|
|
|
||
|
|
When doing coding work in this repository, treat OpenSpec as the source of truth
|
||
|
|
for product intent and requirements. Before implementation, read the relevant
|
||
|
|
change, specs, and tasks under `openspec/`.
|
||
|
|
|
||
|
|
For medium or larger changes, multi-file changes, API/DTO/service-boundary
|
||
|
|
changes, or architecture-impacting changes, update the touched OpenSpec
|
||
|
|
surfaces after implementation.
|
||
|
|
|
||
|
|
## Engineering Principles
|
||
|
|
|
||
|
|
Use these principles as default implementation constraints:
|
||
|
|
|
||
|
|
- Backend code is Go unless an OpenSpec change explicitly revisits the stack.
|
||
|
|
- `agent-farm-go` workflow patterns should be internalized behind typed backend
|
||
|
|
interfaces, not treated as ad hoc shell scripts from request handlers.
|
||
|
|
- SOLID: keep responsibilities clear, dependencies explicit, and extension
|
||
|
|
points narrow.
|
||
|
|
- KISS: choose the simplest design that satisfies the current requirement.
|
||
|
|
- YAGNI: do not add future-facing abstractions, services, queues, plugins, or
|
||
|
|
configuration surfaces until there is a current need.
|
||
|
|
- Evidence-first: prefer tests, builds, smoke checks, and inspectable artifacts
|
||
|
|
over claims.
|
||
|
|
|
||
|
|
## File Size Rule
|
||
|
|
|
||
|
|
No source file should exceed 600 lines.
|
||
|
|
|
||
|
|
If a file approaches 600 lines, split it by responsibility before adding more
|
||
|
|
behavior. Prefer small modules with explicit boundaries over large coordinator
|
||
|
|
files. Generated files, lockfiles, vendored files, and external data snapshots
|
||
|
|
are exempt, but should not be edited manually unless necessary.
|
||
|
|
|
||
|
|
## Design Style
|
||
|
|
|
||
|
|
- Prefer small, cohesive functions and modules.
|
||
|
|
- Keep business rules close to the domain they describe.
|
||
|
|
- Keep workflow orchestration separate from low-level adapters.
|
||
|
|
- Keep learner memory, ontology, grading, progression, and asset generation as
|
||
|
|
separate responsibilities.
|
||
|
|
- Prefer typed contracts for workflow inputs and outputs.
|
||
|
|
- Avoid broad helper packages that become dumping grounds.
|
||
|
|
- Avoid speculative generic frameworks.
|
||
|
|
|
||
|
|
## Validation
|
||
|
|
|
||
|
|
After code changes, run the narrowest meaningful validation first, then broader
|
||
|
|
checks when the touched surface justifies it.
|
||
|
|
|
||
|
|
For planning/spec-only changes, run:
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
openspec validate bootstrap-job-tutor-platform --strict
|
||
|
|
```
|
||
|
|
|
||
|
|
For future code changes, add project-specific build and test commands here once
|
||
|
|
the implementation stack is initialized.
|