AGENTS.md · QwenLM/qwen-code

Sections

1. Working Principles
2. Module-specific Instructions
3. Common Commands
4. Code Conventions
5. Development Guidelines
6. Code Review
7. GitHub Operations
8. Testing, Debugging, and Bug Fixes
9. Submitting PRs
10. Project Directories

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

# AGENTS.md

## Working Principles

### Simplicity First

**Minimum code that solves the problem. Nothing speculative.**
**(This is the principle we care about most.)**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
simplify.

### Core Infrastructure Is Maintainer-Only (triage gate, two-tier rule)

Core modules — `packages/core/src/**`, `packages/*/src/auth/**`,
`packages/*/src/providers/**`, `packages/*/src/models/**`,
`packages/*/src/config/**`, `packages/*/src/tools/**`,
`packages/*/src/services/**`, cross-package changes — are the architectural
backbone. External PRs touching them face a two-tier gate (maintainer-authored
PRs are exempt):

1. **Large-scope `refactor` changes (500+ production logic lines in core,
   excluding test and generated/schema files) → hard block.**
   Skip evaluation entirely — the maintainer exemption above is the sole
   exception. Large-scale core refactors must be maintainer-initiated.
   When counting lines, exclude files matching `*.test.ts`, `*.test.tsx`,
   `*.spec.ts`, `*.spec.tsx`, `__tests__/**`, `*.schema.ts`, `*.schema.json`,
   `*.generated.ts`, and `**/generated/**` — only production logic counts.
   `feat`-type and other non-`refactor` PRs are NOT hard-blocked on size; they
   escalate to the maintainer for awareness instead. A non-blocking advisory
   also applies at 1000+ production logic lines. Breadth alone is not size — a
   low-risk sweep that touches 10+
   files but changes a line or two each is escalated to a maintainer for
   awareness and otherwise judged under Tier 2's 100%-confidence bar, not
   auto-rejected on file count.
2. **Small-scope changes → gate may evaluate, but must be 100% confident.**
   Any doubt at all → escalate to maintainer. "The direction looks correct"
   is not confidence. The gate must name every downstream consumer; if it
   cannot, escalate.

**When in doubt, escalate. Better to wrongly escalate than to wrongly
approve.**

## Module-specific Instructions

Before changing `packages/managed-agent-server/**`, read its
[AGENTS.md](packages/managed-agent-server/AGENTS.md). It supplements
these repository-wide rules with Java verification and service constraints;
the common design, self-audit, and PR workflows still apply.

## Common Commands

### Building

```bash
corepack pnpm install --frozen-lockfile  # Install all dependencies (the tree CI tests)
npm run build      # Build all packages (TypeScript compilation + asset copying)
npm run build:all  # Build everything including sandbox container
npm run bundle     # Bundle dist/ into a single dist/cli.js via esbuild
                   # (requires build first)
```

### Development

```bash
npm run dev        # Run CLI from TypeScript source
```

Runs the CLI via `tsx` with `DEV=true`. Changes to `packages/core` or
`packages/cli` are reflected immediately without rebuilding. Browser Use reuses
its built runtime, like other compiled workspace dependencies. After editing
Browser Use, run `npm run build --workspace=@qwen-code/browser-use` to rebuild
its runtime for dev. Normal `npm install` prepares it automatically.

### Unit Testing

Tests must be run from within the specific package directory, not the project
root.

**Fresh clone or new worktree:** `packages/cli` unit tests import workspace
packages (`@qwen-code/acp-bridge`, `@qwen-code/web-templates`,
`packages/channels/*`, ...) through their built `dist/` output, and
`packages/core` tests import the package's own entry
(`@qwen-code/qwen-code-core`), which also resolves into `dist/`. A plain
`corepack pnpm install --frozen-lockfile` already builds them via the
`prepare` script, but a worktree that shares the main checkout's
`node_modules` (or a deep-cleaned copy) does not have them. If any
prerequisite is missing, a vitest `globalSetup` guard stops the run and names
the fix; build once from the repository root:

```bash
npm run build
```

**Installing dependencies:** CI, release and every workflow install with the
pnpm version pinned in `packageManager` (`corepack pnpm install
--frozen-lockfile`); scripts still run through `npm run`. An additional Git
worktree can use `node scripts/setup-worktree.js`, which runs the same install
from a shared store (≈ 99 MiB on copy-on-write filesystems such as APFS, btrfs,
and XFS with reflink; ≈ 1.2 GiB on ext4) and skips the `prepare` build, so run
`npm run build` before package tests. When dependencies change, edit the
manifest, run `corepack pnpm install` (or `corepack pnpm add`), and commit
`pnpm-lock.yaml`; every CI install runs with `--frozen-lockfile`, so a
lockfile that no longer matches the manifests fails the build.

**Run individual test files** (always preferred):

```bash
cd packages/core && npx vitest run src/path/to/file.test.ts
cd packages/cli && npx vitest run src/path/to/file.test.ts
```

**Update snapshots:**

```bash
cd packages/cli && npx vitest run src/path/to/file.test.ts --update
```

**Avoid:**

- `npm run test -- --filter=...` — does NOT filter; runs the entire suite
- `npx vitest` from the project root — fails due to package-specific vitest
  configs
- Running the whole test suite unless necessary (e.g., final PR verification)

**Test gotchas:**

- In CLI tests, use `vi.hoisted()` for mocks consumed by `vi.mock()` — the
  mock factory runs at module load time, before test execution.

### Integration Testing

Build the bundle first: `npm run build && npm run bundle`

Run from the project root using the dedicated npm scripts:

```bash
npm run test:integration:cli:sandbox:none
npm run test:integration:interactive:sandbox:none
```

Or combined in one command:

```bash
cd integration-tests && \
  cross-env QWEN_SANDBOX=false npx vitest run cli interactive
```

**Gotcha:** In interactive tests, always call `session.idle()` between sends —
ANSI output streams asynchronously.

### Linting & Formatting

```bash