AGENTS.md · alibaba/open-code-review

Sections

1. Development Assistance
2. Project Overview
3. Git Commit Notes
4. License Headers
5. Code Style
6. Provider Presets
7. Testing
8. README

First lines (shown under the repo's Apache-2.0 license)

# Agent Guidelines for open-code-review

This file provides instructions for AI coding assistants working on this project.

## Development Assistance

Below are rules that a contributor must follow during development. If the user does not follow these rules, please warn users about this:

1. **You must disclose in your initial issue or pull request that you used AI/LLM, as well as the tools/models you used.**
2. You should understand every line of code written by AI and know what the AI did.
3. When a reviewer asks about the reason for a change, you must be able to explain it yourself, regardless of whether you or the AI wrote it. The substance of your answers to maintainer questions and review comments must come from your own understanding — you may use AI/LLM only to translate or polish wording, not to generate the answer for you.
4. Your PR should not contain repeated cycles like `AI generated -> fixed -> fixed -> fixed`. This may indicate that you did not review the AI-generated code, but instead let the AI fix issues as they arise, over and over.
5. You must review all code, text, and other content generated by AI/LLM yourself before proactively requesting a review from any member.
6. You must not attribute commits to AI/LLM, including through "Assisted-by", "Co-developed-by", or similar trailers.
7. Do not write overly long commit messages. Important information should go in the PR description rather than in collapsed commit messages.
8. If you are unwilling or unable to do all of the above, please close your issue or pull request.

## Project Overview

open-code-review (`ocr`) is an AI-powered code review CLI tool written in Go (module: `github.com/alibaba/open-code-review`).

## Git Commit Notes

- Before committing, conduct a code review by running:
  ```
  ocr review --audience agent --background "briefly summarize the background requirements"
  ```
- Commit messages must be written in English.
- Verify line endings. Line endings must be LF, not CRLF. Run `git add --renormalize .` to correct line endings and commit them. New binary files must have their extensions added to .gitattributes. 

## License Headers

- Every source file (`.go`, `.js`, `.mjs`, `.ts`, `.tsx`, `.kt`, `.kts`, `.sh`, `.py`, `.css`) must have an SPDX license header.
- After creating new files, run `make license-add` to add the header automatically. It picks the comment syntax by extension: `//`, `#`, or a `/* */` block for CSS.
- An extension belongs on that list once the repository actually holds files of that type and the comment can simply be prepended. `.html` meets neither bar cleanly — its `<!DOCTYPE html>` has to stay on the first line — so it is not covered yet.

## Code Style

- **Comment sparingly, and only to explain "why".** Do not add comments that restate what the code already says (`// increment i`), narrate the change itself (`// newly added`, `// changed to fix ...` — that belongs in the commit message or PR description), quote pull request or issue numbers from the upstream repository, or leave TODO/placeholder chatter. A comment earns its place only when it captures intent, a non-obvious constraint, or a subtlety the code cannot express on its own.
- After writing code, run `make check`. It formats and tidies in place, so there is no need to run `gofmt` or `go vet` separately.
- **Source files are written in English** — comments, identifiers and strings alike. `make english-check` enforces this in CI. It flags any letter outside ASCII, whichever the writing system (Han, kana, Hangul, Cyrillic, and equally the diacritics that spell German or Vietnamese), plus combining accents and fullwidth punctuation (`：`, `（`), which is easy to leave behind in an otherwise English sentence. Symbols and emoji (`─ → ≥ ✅`) pass, since they are not letters. Prose spelled entirely in ASCII (`Loeschen der Datei`, or a romanised transcription) takes a dictionary to spot and stays a matter for review.
- **Translated prose has its own homes, none of them scanned.** `docs/i18n/README.<locale>.md` and `docs/i18n/CONTRIBUTING.<locale>.md` (`zh-CN`, `ja-JP`, `ko-KR`, `ru-RU`); the doc pages under `pages/src/content/docs/<locale>/` (`en`, `zh`, `ja`, `ru`, Markdown throughout); and the UI copy tables in `pages/src/i18n/<locale>.ts`. Markdown is out of scope by extension, so translations go there freely. The i18n tables are `.ts` and would be scanned, so they are exempt by prefix instead — translated UI strings belong in those tables rather than inline in a component.
- **Two escape hatches for the exceptional case, narrower one preferred.** Append an `allow-non-english: <reason>` marker comment to the offending line — the right choice for a handful of lines, such as an encoding fixture or a language-switcher label, and it leaves the rest of the file protected. Only for a whole tree that is inherently non-English, add a prefix to `allowedPrefixes` in `scripts/verify-english-only.go`; that list records each exemption's reason and the removal conditions for temporary translation exemptions.

## Provider Presets

When changing built-in provider metadata or model lists in
`internal/llm/providers.go`, run `go generate ./internal/llm` from the
repository root. Commit both generated files with the registry change;
do not edit them by hand:

- `extensions/frontend/src/shared/providers.generated.ts`
- `extensions/idea/src/main/kotlin/com/alibaba/opencodereview/idea/services/ProviderNames.generated.kt`

## Testing

- Run unit tests with `make test`, not `go test` directly.
- `make test` sets `LC_ALL=C` to ensure git outputs English messages.
- When writing or modifying code, add necessary unit tests to maintain coverage. The project enforces a 90% coverage threshold via `make coverage`.

## README

- When modifying README.md, always sync the changes to all localized versions:
  - docs/i18n/README.zh-CN.md
  - docs/i18n/README.ja-JP.md
  - docs/i18n/README.ko-KR.md
  - docs/i18n/README.ru-RU.md