Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (56 loc) · 3.34 KB

AGENTS.md

File metadata and controls

73 lines (56 loc) · 3.34 KB
Raw

AGENTS.md

Guidance for AI coding agents in this repo. Human contributors: see CONTRIBUTING.md.

Workflow

  • Clarify the design before implementing. For anything non-trivial, agree on the approach first; prefer a short design note over jumping to code.
  • One unit of change per commit. Never mix unrelated changes. Present the change for review before committing.
  • Every change ships with tests. Run local CI before calling it done, and do not claim it passes without running it.
  • Verify against the code and the tools: read before you answer, run before you assert.

Local CI:

cargo fmt --all --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features

Writing: code, comments, docs, commits

  • Concise and to the point. No fluff. Explain the non-obvious; do not narrate the obvious.
  • ASCII only. No em-dash and no --; write -. Do not use any non-ASCII glyph: write -> for the right arrow, <-> for the left-right arrow, != for not-equal, straight quotes for curly ones, and the same for every other Unicode symbol. Applies everywhere, including this file.
  • Comments justify why, not what. Delete any comment that restates the code.
  • Do not use the word "seam"; say boundary, interface, or extension point.
  • Do not use "bespoke"; say "custom".

Commits

  • Conventional Commits (see CONTRIBUTING.md). Write the subject in the present tense, imperative voice: feat: add fetch TTL, not added or adds.
  • Keep the body minimal. The subject alone is often enough; add body lines only for the non-obvious why. Do not restate the diff or enumerate every file changed.
  • Disclose AI with an Assisted-by: Claude:claude-opus-4-8 trailer. Never Co-Authored-By, and never add a human's Signed-off-by.

Tests

  • Unit tests inline (#[cfg(test)] mod tests); public-surface tests in tests/.
  • Put helpers after the tests that use them.
  • Prefer deterministic time: drive tokio's paused clock, not sleeps or yield_now loops.

Terminology

  • upstream: the origin git server the proxy fetches from. The proxy holds a single read-only credential for it and never writes to it.
  • mirror: the local bare repository (clone --mirror) the proxy serves clients from and keeps fresh with incremental fetches.
  • serve: responding to a client's info/refs / git-upload-pack from the mirror.
  • git-cache-proxy is strictly read-only and pull-only. Any change that could push or proactively replicate to upstream is out of scope.

Code conventions

  • All git protocol work is delegated to the system git binary. Do not reimplement pack negotiation; shell out to git so protocol correctness (v2, shallow, partial clones) is free.
  • Import a type by one path and use it consistently (e.g. a single use std::sync::Arc, not mixed inline std::sync::Arc paths).
  • Prefer tokio::fs in async paths unless std::fs is clearly fine (small, at startup, no blocking concern).
  • Document public items with rustdoc; keep it accurate and free of drift.

CI workflows

  • GitHub Actions live in .github/workflows. Write the workflow name:, every job name, and every named step in Sentence case, matching ci.yml (e.g. name: CI, Check formatting).
  • Keep workflows minimal and scoped to one purpose; prefer the built-in GITHUB_TOKEN over a personal access token.