66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# Agent Guidelines for XControl
|
|
|
|
## Repository scope
|
|
These instructions apply to the entire repository. Create a more specific `AGENTS.md`
|
|
inside a subdirectory only when you need to override or augment the guidance below for
|
|
that subtree.
|
|
|
|
## Project overview
|
|
XControl is a polyglot monorepo that ships:
|
|
- Multiple Go services (API server, account service, RAG server, supporting CLIs) under
|
|
the top-level Go module `xcontrol`.
|
|
- A Next.js dashboard (`dashboard/`) implemented in TypeScript with Tailwind CSS and
|
|
Vitest/Playwright tests.
|
|
- CMS configuration, SQL migrations, deployment manifests, and documentation that are
|
|
consumed by the services and UI.
|
|
|
|
## General expectations
|
|
- Match the existing language of the file (English vs. Chinese or bilingual) and retain
|
|
the bilingual structure when you touch documentation that already mixes both.
|
|
- Prefer structured logging (`log/slog`) or existing helper utilities over raw
|
|
`fmt.Println` in Go code.
|
|
- Keep configuration files and generated assets deterministic. If you edit files under
|
|
`config/`, `docs/cms/`, or `scripts/`, mention any required regeneration steps in your
|
|
commit message or PR description.
|
|
|
|
## Go code (all directories except `dashboard/`)
|
|
- Format Go code with `gofmt` (or `go fmt ./...`) before committing.
|
|
- Organize imports using `goimports` if available; otherwise maintain the existing
|
|
standard library / third-party separation.
|
|
- Run `go test ./...` from the repository root (or a narrower package path) after
|
|
changing Go files. Use `make test` in submodules such as `rag-server/` when you need the
|
|
module-specific workflow.
|
|
- Keep configuration structs in sync with their YAML/JSON sources and update default
|
|
values when you add new fields.
|
|
|
|
## TypeScript / Next.js dashboard (`dashboard/`)
|
|
- Use `yarn` (not `npm` or `pnpm`). Install dependencies with `yarn install` and run
|
|
scripts with `yarn --cwd dashboard <script>`.
|
|
- Format code with the existing ESLint rules by running `yarn --cwd dashboard lint
|
|
--fix` when possible. Follow the 2-space indentation style and single-quote string
|
|
literals you see in the current codebase.
|
|
- Run `yarn --cwd dashboard lint` and the relevant tests (`yarn --cwd dashboard test`
|
|
and/or `yarn --cwd dashboard test:e2e`) when you touch dashboard code.
|
|
- Avoid introducing runtime-only environment variables; prefer adding entries to
|
|
`dashboard/config/runtime-service-config.yaml` so that environments stay declarative.
|
|
|
|
## Documentation and Markdown (`docs/`, `README.md`, etc.)
|
|
- Wrap prose at a reasonable width (~100 characters) and preserve existing heading
|
|
hierarchies.
|
|
- When documenting commands or configuration, prefer fenced code blocks with explicit
|
|
language identifiers (e.g., `bash`, `go`, `json`).
|
|
- Update cross-references if you rename or relocate files that are linked in the docs.
|
|
|
|
## Database and migrations
|
|
- For schema changes, update both the SQL migration under the relevant `sql/` directory
|
|
and any Go structs/DTOs that map to the same tables.
|
|
- Provide idempotent migration steps where possible and document required manual steps
|
|
in the accompanying README or commit message.
|
|
|
|
## Testing summary
|
|
Before shipping changes, run the narrowest applicable subset of these commands:
|
|
- `go test ./...` (Go services)
|
|
- `yarn --cwd dashboard lint`
|
|
- `yarn --cwd dashboard test`
|
|
- `yarn --cwd dashboard test:e2e` (when you modify Playwright specs or end-to-end flows)
|