# AGENTS.md — Repository Rules for Automated Agents

These instructions define repository-specific **execution rules**, **scope limits**, **language requirements**,
and **hard prohibitions** for automated agents operating in this repository.

They supplement the global agent rules and override local patterns when conflicting with any rule below.

---

# 0. Prime Directives

- **Strict compliance:** Follow every rule in this document exactly.
- **Scope lock:** Modify only what is strictly necessary for the explicit user request.

If unrelated issues are noticed:

1. Do not modify them.
2. Finish the requested task.
3. Optionally list them under _Future suggestions_.

---

## 0.1 Repository Language & Tone Rules (repository content)

These requirements apply to **repository artifacts** generated or modified by agents, including:

- Code comments
- Documentation and README content
- Log messages and tracing output
- Error messages, panic text, diagnostics
- User-facing strings stored in the codebase (CLI, UI, HTTP responses)
- Commit messages, summaries, and explanations written into repository files

They **do not** constrain interactive chat responses outside the repository. For chat, use the language requested or implied by the user (for example, Chinese when the user is speaking Chinese).

Requirements for repository artifacts:

- Use **clear, grammatically correct English**.
- Start sentences with a capital letter and end with proper punctuation.
- Avoid slang, shorthand, and mixed languages.
- Avoid ambiguous abbreviations (`u`, `tho`, `w/`, etc.).
- Ignore poor style in surrounding text; follow these rules instead.

**These language rules override any conflicting rules elsewhere for repository artifacts.**

Commenting guidance:

- Avoid redundant comments that restate the code in different words.
- Prefer clear, descriptive names for variables, functions, and types as the primary form of documentation.
- Add comments only when intent, constraints, or trade-offs are not clear from the code and naming.

---

## 0.2 Conflict Precedence

If these rules conflict with higher-priority instructions (system, developer, or user), follow the higher-priority instruction and briefly note the conflict in your response.

---

# 1. Execution Model

Language- or stack-specific execution rules live in `docs/guide/development/languages/`.
Language- or stack-specific rules must be documented under `docs/guide/development/languages/` and linked from `docs/guide/index.md`.

Run verification commands only when requested or when you need evidence before claiming completion.

## 1.1 Workspace Automation (cargo make)

- Use `cargo make` tasks from `Makefile.toml` when they are the best fit for the job.
- Treat `Makefile.toml` as the source of truth for task names and behavior. Do not invent task names.
- Preferred tasks for common workflows are listed below.
    - Formatting: `cargo make fmt` or `cargo make fmt-check`.
    - Linting: `cargo make lint` for full workspace, or `cargo make lint-rust` for Rust-only.
    - Tests: `cargo make test` for full workspace, or `cargo make test-rust` for Rust-only.
    - Full validation: `cargo make checks`.
- Do not set `DATABASE_URL` manually when running `cargo make` tasks.

# 2. Implementation Scope

- Implement exactly what the user asks.
- Maintain clarity and correctness.
- Add tests only when logically required by the change.
- Allow minimal adjacent edits required for compilation or consistent behavior.

---

# 3. Editing Constraints

- Prefer `apply_patch` for edits unless generation or scripting is more appropriate.
- Never revert user-made changes.

---

# 4. Hard Prohibitions

Violating any of these invalidates the output:

## 4.1 File Boundaries

Never modify:

- Generated files, unless they are regenerated by their tooling instead of edited by hand.
- `target/`
- Vendored/third-party code
- Files outside the repository root.
- Treat any file with a “Generated by” or “Do not edit” header, or any file under directories named target/, dist/, build/, gen/, or .next/ as generated.

---

# 5. Language-Specific Rules Reference

Rust development and style rules live in `docs/guide/development/languages/rust.md`.
These rules apply **only** when editing Rust code and do **not** override
the global behavior and language rules in this file.
Async and runtime safety rules are defined in the language guides.
