mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-07-03 20:40:37 +00:00

Files

dennis zhuang 3b8f55e490 docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

* docs(agents): add per-crate guides, architecture invariants, and generated-files list

Add agent/contributor navigation docs modeled on the AGENTS.md convention:

- Per-crate AGENTS.md for hot crates (mito2, metric-engine, flow, frontend,
  meta-srv): module map, read/write paths, change-coupling points, test
  commands, and gotchas.
- .agents/architecture-invariants.md: repo-wide rules that clippy and the
  style guide do not cover (format compatibility, crate layering, async
  runtimes, error handling, experimental gating, the DataFusion fork).
- .agents/generated-files.md: tool-generated artifacts that must not be
  hand-edited (sqlness .result, config.md, dashboards, build.rs output, proto).
- Anchor the .gitignore CLAUDE.md/AGENTS.md rules to the repo root so per-crate
  AGENTS.md files are tracked while root-level personal config stays ignored.

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* chore: update crate AGENTS.md and fix config.md path

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* docs(agents): fix DataFusion patch layout and SQL query lifecycle order

Address review feedback on #8346:

- architecture-invariants: the DataFusion sub-crates pin an exact crates.io
  version in [workspace.dependencies] and are redirected to the fork rev in
  [patch.crates-io]; the two sections hold different forms, not the same rev.
- frontend: the SQL query lifecycle runs the pre_parsing/post_parsing
  interceptors around parsing, before the per-statement permission check.

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

---------

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

2026-06-24 09:14:09 +00:00

skills

chore: share agent release skills (#8336 )

2026-06-19 05:15:16 +00:00

architecture-invariants.md

docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

2026-06-24 09:14:09 +00:00

generated-files.md

docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

2026-06-24 09:14:09 +00:00

README.md

docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

2026-06-24 09:14:09 +00:00

README.md

Agent Resources

Shared resources for coding agents (Codex, Claude Code, ...) and contributors.

Skills

Shared agent skills live in .agents/skills.

Codex automatically discovers repo skills from .agents/skills.
Claude Code reads the same skills through .claude/skills, which is a symlink to this directory.
Add or update shared skills under .agents/skills/<skill-name>/SKILL.md.
If a new skill does not appear, restart the agent or start a new thread.

Per-crate guides

Hot crates carry an AGENTS.md next to their code as a navigation aid (module map, read/write paths, change-coupling points, test commands, gotchas):

src/mito2/AGENTS.md — primary time-series storage engine
src/metric-engine/AGENTS.md — metrics engine (logical/physical regions)
src/flow/AGENTS.md — stream processing / continuous aggregation
src/frontend/AGENTS.md — request entry point and orchestration
src/meta-srv/AGENTS.md — metadata and cluster coordination

Architecture invariants

architecture-invariants.md lists repo-wide rules that are easy to violate and expensive to get wrong (format compatibility, crate layering, async runtimes, error handling, feature gating, the DataFusion fork).

Generated files

generated-files.md lists tool-generated artifacts that must not be hand-edited (sqlness .result, config.md, dashboards, ...).