mirror of
https://github.com/coder/coder.git
synced 2026-10-31 19:36:41 +08:00
Michael Suchacz
9d6ef1e701
## Summary
Streamlines the agent instruction files, cutting per-session token
overhead by roughly 65%.
The core design change: `AGENTS.md` no longer `@`-imports WORKFLOWS.md,
package.json, the eight detailed guides, or `AGENTS.local.md` into every
session. Guidance moves from guaranteed-in-context to load-on-demand
through a routing table, betting that one-line guardrail summaries plus
links are enough to make agents pull the right doc when a task needs it.
- `AGENTS.md` (251 -> 80 lines): a routing table to the canonical docs
in `.claude/docs/`, the essential command table, and one-line guardrails
for the architectural footguns (SQLC workflow plus audit table, OAuth2
error conformance, chatd architecture-doc rule, Swagger annotations,
`InTx` discipline, test concurrency, workflow `permissions: {}`,
mandatory git hooks, commit/PR title format).
- `site/AGENTS.md` (364 -> 89 lines): keeps the FE1-FE10 contract
summary, TypeScript LSP navigation, pnpm command table, React Compiler
boundaries, accessibility rules, and the pre-PR `frontend-review`
requirement. Drops the generic React tutorial sections that restate
framework documentation.
- The persona and relationship prose ("Our relationship", foundational
rules) is deliberately removed. The behavioral gates worth keeping for
every agent survive as one-liners: get explicit permission before
excepting a rule, discuss architectural decisions before implementing,
and answer questions instead of jumping to implementation.
- Unique operational content is relocated rather than deleted:
Playwright failure-artifact paths and the CI `playwright-artifacts-`
naming convention move to `.claude/docs/AGENT_FAILURES.md`; the
`React.useId()` rule, the `key={String(booleanState)}` remount footgun,
date-as-prop Storybook determinism, and the suppression-comment rule
(updated from `eslint-disable` to `biome-ignore` to match current
tooling) move to `.claude/docs/FRONTEND_PATTERNS.md`.
Content reflects current main: the chatd rule says agents leave TODOs
and the human PR author writes the architecture doc, and MUI/Emotion are
described as removed, not deprecated.
Note for Claude Code users: `CLAUDE.md` symlinks to `AGENTS.md`, so
detailed workflow docs (hook internals, the new-feature checklist,
`AGENTS.local.md`) are no longer auto-loaded into every session; agents
must follow the links.
## Validation
- `pnpm exec markdownlint-cli2` on all four touched files: 0 errors
- `pnpm exec markdown-table-formatter --check` on all four touched
files: pass
- `make lint/emdash`: pass
- `make lint/agents`: pass
- All relative links verified to resolve
> Mux created this PR and description on behalf of Mike.
86 lines
6.4 KiB
Markdown
86 lines
6.4 KiB
Markdown
# Coder Development Guidelines
|
|
|
|
Make the smallest correct change, follow existing patterns, and verify the result. Ask only when the request is unclear, a meaningful design choice remains, or the action is destructive. If you want an exception to any rule in these documents, stop and get explicit permission first.
|
|
|
|
Prioritize correctness over agreement. State uncertainty instead of guessing, and push back on technically unsound requests with evidence.
|
|
|
|
## Task-specific guidance
|
|
|
|
Load only the guidance relevant to the task:
|
|
|
|
| Scope | Guidance |
|
|
|-----------------------------------------------------|---------------------------------------------------------|
|
|
| Development servers, Git, hooks, and routine checks | [WORKFLOWS.md](.claude/docs/WORKFLOWS.md) |
|
|
| API endpoints and Swagger | [WORKFLOWS.md](.claude/docs/WORKFLOWS.md) |
|
|
| Go | [GO.md](.claude/docs/GO.md) |
|
|
| Tests and concurrency | [TESTING.md](.claude/docs/TESTING.md) |
|
|
| Database and SQLC | [DATABASE.md](.claude/docs/DATABASE.md) |
|
|
| OAuth2 and authorization | [OAUTH2.md](.claude/docs/OAUTH2.md) |
|
|
| Architecture | [ARCHITECTURE.md](.claude/docs/ARCHITECTURE.md) |
|
|
| Troubleshooting | [TROUBLESHOOTING.md](.claude/docs/TROUBLESHOOTING.md) |
|
|
| Observability | [OBSERVABILITY.md](.claude/docs/OBSERVABILITY.md) |
|
|
| Isolation, ports, and cleanup | [DEV_ISOLATION.md](.claude/docs/DEV_ISOLATION.md) |
|
|
| Failure reports | [AGENT_FAILURES.md](.claude/docs/AGENT_FAILURES.md) |
|
|
| PR descriptions | [PR_STYLE_GUIDE.md](.claude/docs/PR_STYLE_GUIDE.md) |
|
|
| Existing docs prose | [docs style guide](docs/.style/style-guide/README.md) |
|
|
| Docs scope and routing | [content guidelines](docs/.style/content-guidelines.md) |
|
|
| Docs structure and research | [DOCS_STYLE_GUIDE.md](.claude/docs/DOCS_STYLE_GUIDE.md) |
|
|
| New, moved, or restructured docs | [write-docs skill](.claude/skills/write-docs/SKILL.md) |
|
|
| Frontend | [site/AGENTS.md](site/AGENTS.md) |
|
|
|
|
For changes under `site/src/`, also read [FRONTEND_PATTERNS.md](.claude/docs/FRONTEND_PATTERNS.md). For chatd work, read [coderd/x/chatd/ARCHITECTURE.md](coderd/x/chatd/ARCHITECTURE.md). When the docs style guide and the content guidelines conflict, the content guidelines govern scope and routing.
|
|
|
|
## Workflow
|
|
|
|
- Inspect the working tree before editing. For an existing PR, check out its branch first.
|
|
- Discuss architectural decisions such as framework changes, major refactoring, and system design before implementing them. Routine fixes and clear implementations do not need discussion.
|
|
- When asked a question, answer the question instead of jumping to implementation.
|
|
- Install and use the repository Git hooks. Never bypass them with `--no-verify`. Wait for slow first runs while caches warm.
|
|
- Prefer targeted tests and checks while iterating. Run the broader checks required by the affected area before handoff.
|
|
- Do not force-push unless explicitly requested.
|
|
- Commit and PR titles use `type(scope): message`. A scope must be a real path containing every changed file. Use a broader scope or no scope for cross-cutting changes.
|
|
|
|
## Essential commands
|
|
|
|
| Task | Command |
|
|
|-------------------|--------------------------|
|
|
| Develop | `./scripts/develop.sh` |
|
|
| Build | `make build` |
|
|
| Build slim | `make build-slim` |
|
|
| Test | `make test` |
|
|
| Test one | `make test RUN=TestName` |
|
|
| Race test | `make test-race` |
|
|
| Lint | `make lint` |
|
|
| Generate | `make gen` |
|
|
| Format | `make fmt` |
|
|
| Pre-commit checks | `make pre-commit` |
|
|
| Pre-push checks | `make pre-push` |
|
|
|
|
Docs use `pnpm run format-docs` and `pnpm run lint-docs`. Frontend commands live in `site/AGENTS.md`.
|
|
|
|
## Repository guardrails
|
|
|
|
- **Database changes:** edit `coderd/database/queries/*.sql`, run `make gen`, update `enterprise/audit/table.go` for audit errors, then run `make gen` again.
|
|
- **OAuth2:** return RFC-compliant errors such as `writeOAuth2Error(...)`. Public endpoints that need system access use `dbauthz.AsSystemRestricted`.
|
|
- **Chatd:** when a change affects the documented architecture, do not edit the architecture document yourself. Leave TODO items in the affected sections; the human PR author writes the actual updates.
|
|
- **Public API:** add the required Swagger annotations for new public HTTP endpoints.
|
|
- **Transactions:** keep `InTx` work on the transaction handle. Prefer explicit database-to-SDK converters.
|
|
- **Concurrent tests:** call `t.Parallel()`, use unique identifiers, and do not use `time.Sleep` to mask timing problems.
|
|
- **Frontend:** reuse shared UI primitives and test components or pages through Storybook stories. Plain Vitest files are for pure logic only.
|
|
- **GitHub Actions:** set top-level `permissions: {}` and grant only required permissions per job.
|
|
|
|
## Code and writing style
|
|
|
|
- Follow the [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md) for Go code.
|
|
- Use language-server navigation when available.
|
|
- Name code for what it does, not its implementation or history. Wrap errors with context.
|
|
- Document exported symbols with idiomatic Go doc comments or JSDoc.
|
|
- Avoid unrelated edits. Preserve comments that explain non-obvious behavior.
|
|
- Comments must be concise and substantive. Explain behavior, constraints, or rationale, not the history of the edit.
|
|
- Do not use em dashes, en dashes, or spaced double hyphens as punctuation in code, comments, strings, or documentation.
|
|
- Ensure files end with a newline.
|
|
|
|
## Local configuration
|
|
|
|
Read `AGENTS.local.md` when present. It may be gitignored and is not imported automatically.
|