From 714b7e8c2288bea9f7151c0aabb478515565ad3a Mon Sep 17 00:00:00 2001
From: shenlan <manbuzhe2009@qq.com>
Date: Fri, 31 Oct 2025 21:27:40 +0800
Subject: [PATCH] docs: add repository agent guidelines (#613)

---
 AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3fe5708
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,65 @@
+# 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)