d7b52f0876
* chore: add versioned Greptile review policy * chore: preserve review learnings and papercuts * docs: align Claude and agent guidance * docs: add shared engineering principles * docs: trim engineering principles
26 lines
2.4 KiB
Markdown
26 lines
2.4 KiB
Markdown
# Agent guidance
|
|
|
|
## Engineering principles
|
|
|
|
- Prefer simple, readable, flat code with minimal indirection.
|
|
- Search for existing implementations and installed libraries before creating new helpers or abstractions.
|
|
- Abstract when it prevents meaningful drift and makes the result simpler to maintain. Avoid speculative or one-use abstraction layers.
|
|
- Keep product data normalized and relationships explicit. Do not encode relational data in JSON or text merely to avoid joins.
|
|
- For new application-backed backend functionality, default to: TanStack server function → service → repository.
|
|
- Keep schema changes, queries, and mutations compatible with both SQLite and Postgres.
|
|
- Use idiomatic TypeScript. Use Zod to validate untrusted data and narrow runtime values at trust boundaries.
|
|
- Prefer established project helpers and libraries over hand-rolled implementations.
|
|
- Prefer idiomatic TanStack Query, Router, and Form patterns for server state, routing, and submitted forms.
|
|
|
|
## Log papercuts
|
|
|
|
When small, non-blocking repository friction occurs—a retried tool call, confusing setup step, flaky command, stale cache, misleading error, or non-obvious gotcha—use the `papercuts` skill and append it to `.agents/PAPERCUTS.md` in the moment. Continue the current task. Real bugs and tracked work are not papercuts, and sensitive data must never be logged.
|
|
|
|
Do not mine an entire session for papercuts or start a broad cleanup unless the user explicitly asks.
|
|
|
|
## Preserve review learnings
|
|
|
|
After a merge-ready or other code review verifies a finding, use `maintain-greptile-rules` only when the finding exposes a recurring or high-risk repository invariant that existing `.greptile/` context and automated checks do not capture. Do not promote one-off bugs or preferences into permanent review rules.
|
|
|
|
Changes to `.greptile/**`, `AGENTS.md`, `CLAUDE.md`, `.agents/skills/**`, and `.github/**` alter the review control plane and must receive explicit maintainer review. CODEOWNERS requests that review; where repository settings allow, enable GitHub's requirement for code-owner approval. Repository-specific rules live in `.greptile/`; maintainers should configure or retain a minimal org-enforced Greptile baseline for external-contribution, secret, authentication, billing, CI, and rule-tampering risks. Agents should report an unverified or missing baseline and must not mutate dashboard or organization rules without explicit user authorization.
|