AGENTS.md · chaitin/PandaWiki

Sections

1. Source Of Truth
2. Repository Layout
3. Architecture Expectations
4. Tooling Versions And Basics
5. Install Commands
6. Build Commands
7. Test Commands
8. Lint And Format Commands
9. Code Style: Go
10. Code Style: TypeScript / React
11. Naming Conventions
12. Error Handling Expectations
13. Generated Code And API Clients
14. Practical Guidance For Agents
15. Verification Checklist

First lines (shown under the repo's AGPL-3.0 license)

# AGENTS.md

This file is for coding agents working in `PandaWiki`.
Prefer small, targeted changes that match the repository's existing patterns.
Communicate with the user in Chinese unless they explicitly ask otherwise.

## Source Of Truth

- There is no existing `AGENTS.md` in this repository.
- No Cursor rules were found in `.cursor/rules/` or `.cursorrules`.
- No Copilot instructions were found in `.github/copilot-instructions.md`.
- Root `CLAUDE.md` exists and should be treated as repository guidance.
- Key note from `CLAUDE.md`: respect backend layer boundaries and use Chinese for communication.

## Repository Layout

- `backend/`: Go backend services, APIs, workers, migrations, docs.
- `web/`: pnpm workspace for frontend apps.
- `web/admin/`: React + Vite admin console.
- `web/app/`: Next.js user-facing web app.
- `sdk/`: SDK-related code.

## Architecture Expectations

- Backend follows a layered structure.
- Put business logic in `backend/usecase/`.
- Keep HTTP-specific logic in `backend/handler/`.
- Keep persistence and external data access in `backend/repo/`.
- Put shared request/response and domain models in `backend/domain/` and `backend/api/`.
- Do not move business rules into handlers just to finish a feature quickly.

## Tooling Versions And Basics

- Go version: `1.24.3` from `backend/go.mod`.
- Frontend package manager: `pnpm` only.
- Admin app build tool: Vite.
- User app build tool: Next.js.
- Backend formatting/linting is driven by `gofmt`, `goimports`, and `golangci-lint`.
- Frontend formatting is primarily Prettier.

## Install Commands

Run these from the repository root unless noted otherwise.

### Backend

- Install Go dependencies: `cd backend && go mod tidy`
- Build all backend packages: `cd backend && go build ./...`

### Frontend

- Install web dependencies: `cd web && pnpm install`
- Start both frontend apps: `cd web && pnpm dev`

## Build Commands

### Backend

- Build all packages: `cd backend && go build ./...`
- Build one package: `cd backend && go build ./usecase`
- Generate swagger/wire code: `cd backend && make generate`
- Generate pro swagger/wire code: `cd backend && make generate_pro`

### Frontend

- Build all web apps: `cd web && pnpm build`
- Build admin only: `cd web/admin && pnpm build`
- Build app only: `cd web/app && pnpm build`
- Analyze admin build: `cd web/admin && pnpm build:analyze`

## Test Commands

### Backend

- Run all tests: `cd backend && go test ./...`
- Run one package: `cd backend && go test ./usecase`
- Run one test by name in one package: `cd backend && go test ./usecase -run TestName`
- Run one test with verbose output: `cd backend && go test ./usecase -run TestName -v`
- Run one package with race detector when needed: `cd backend && go test -race ./usecase`

### Frontend

- `web/admin` currently has no dedicated test script in `package.json`.
- `web/app` currently has no dedicated test script in `package.json`.
- For frontend verification, use lint, typecheck, and build as the practical test substitute.
- Admin typecheck via build pipeline: `cd web/admin && pnpm build`
- App lint: `cd web/app && pnpm lint`

## Lint And Format Commands

### Backend

- Lint backend: `cd backend && golangci-lint run`
- Full backend lint target: `cd backend && make lint`
- Format one file/package: `cd backend && gofmt -w path/to/file.go && goimports -w path/to/file.go`
- `cd backend && make lint` is required before commit for any backend code change.

Notes:

- `make lint` also runs generation steps and `go mod tidy`; it is heavier than `golangci-lint run`.
- `make lint` already covers backend formatting via configured formatters, so agents should treat it as the required backend verification step before commit.
- `backend/.golangci.toml` enables standard linters and formatters.

### Frontend

- Root formatting: `cd web && pnpm exec prettier --write .`
- Admin lint one file or folder: `cd web/admin && pnpm exec eslint src/path/to/file.tsx`
- App format: `cd web/app && pnpm format`
- App format check: `cd web/app && pnpm format:check`
- App lint: `cd web/app && pnpm lint`

## Code Style: Go

- Use `gofmt`/`goimports`; do not hand-format imports.
- Keep imports grouped by standard library, third-party, then local modules.
- Use tabs and standard Go formatting.
- Exported names use Go PascalCase; unexported names use camelCase.
- Receiver names should be short and consistent, usually `u`, `h`, `r`.
- Keep functions focused; prefer extracting domain logic into `usecase` over large handlers.
- Return wrapped errors with context using `fmt.Errorf("...: %w", err)`.
- Use `errors.Is` for sentinel checks.
- Log internal details, but return user-facing messages from handlers.
- Follow existing pattern: log with `u.logger.Error(...)` or `h.NewResponseWithError(...)` rather than panicking.
- Prefer explicit structs over untyped maps unless responding with a tiny ad hoc payload.
- Respect context propagation. Use `c.Request().Context()` in handlers.
- For streaming/SSE paths, preserve existing event shapes and flushing behavior.

## Code Style: TypeScript / React

- Follow Prettier formatting and the existing single-quote style.
- Use path aliases like `@/request/...` and `@/store` in admin code.
- Prefer explicit types for props and request payloads.
- Avoid `any`; lint only warns today, but new code should use concrete types where practical.
- Use `type` for simple object aliases and event payloads; use `interface` for component props when already idiomatic nearby.
- Components are function components with hooks.
- Keep state local unless it is shared across routes or features.
- Clean up subscriptions/AbortControllers/SSE clients in `useEffect` cleanup or modal close handlers.
- Reuse generated request types from `@/request/types` when available.
- Do not edit generated swagger client files unless absolutely necessary; prefer wrappers like `nodeStream.ts` for special protocols.
- Match existing UI libraries: MUI plus `@ctzhian/ui`.

## Naming Conventions

- Backend request structs end with `Req`, response structs with `Resp`.
- Usecase methods are verbs or verb phrases, e.g. `SummaryNode`, `MoveNode`.
- Frontend modal and page components use PascalCase filenames and component names.
- Request helpers in admin use verb-based names from generated swagger files or descriptive wrapper names.

## Error Handling Expectations

- Never swallow backend errors silently.
- If an error is user-actionable, return a clear message from the handler.
- If an error is for diagnostics only, log the wrapped error and return a generic message.
- In frontend code, surface actionable failures with `message.error(...)`.
- For async UI actions, always stop loading state in both success and error paths.
- For streaming flows, handle both transport errors and protocol-level `error` events.

## Generated Code And API Clients

- `web/admin/src/request/*` contains generated swagger client code.