菜单
Sync docs with code, update docs, doc drift, are docs up to date, audit documentation, spec is wrong, doc is stale, check documentation, verify specs, docs out of date, after code changes affecting documented behavior.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | doc-sync |
| description | Sync docs with code, update docs, doc drift, are docs up to date, audit documentation, spec is wrong, doc is stale, check documentation, verify specs, docs out of date, after code changes affecting documented behavior. |
Detect and fix drift between FrogDB's documentation and the actual codebase. Documentation
lives in website/src/content/docs/ (architecture, operations, guides), plus project docs
(CLAUDE.md, README.md, AGENTS.md), and testing/jepsen/README.md.
When specific code changes have been made (you can see them in git diff or the user describes them):
git diff --name-only (or use the user's description) to identify changed filesreferences/doc-map.md to find which docs reference those code areasWhen the user says "I renamed X to Y" or "I changed X":
Systematic scan of all documentation in priority order. Use references/checkable-assertions.md
as a checklist of machine-verifiable claims.
Priority order:
| Check | Source of Truth | Docs That Reference It |
|---|---|---|
| Workspace members list | Cargo.toml [workspace] members | REPO.md, ARCHITECTURE.md, INDEX.md |
| Crate count | Cargo.toml member count | ARCHITECTURE.md ("5 crates"), INDEX.md |
| Crate names | Cargo.toml [workspace.dependencies] internal crates | All docs mentioning frogdb-* |
| Edition | Cargo.toml [workspace.package] edition | REPO.md |
| Dependency versions | Cargo.toml [workspace.dependencies] | REPO.md code blocks |
| Cross-doc links | ](*.md) patterns in all docs | All spec docs |
| File paths in docs | Paths like crates/lua/ | REPO.md, ARCHITECTURE.md |
How to check:
Cargo.toml for ground truth| Check | Source of Truth | Docs That Reference It |
|---|---|---|
| Struct/trait definitions in code blocks | Actual source files | ARCHITECTURE.md, EXECUTION.md, STORAGE.md, AUTH.md |
| Config keys and defaults | crates/server/src/config/ | CONFIGURATION.md, DEPLOYMENT.md |
| Command lists by type | crates/commands/src/*.rs | types/*.md, COMMANDS.md |
| Public API re-exports | lib.rs files | REPO.md |
How to check:
| Check | Source of Truth | Docs That Reference It |
|---|---|---|
| Justfile recipe names | Justfile | REPO.md, CLAUDE.md, TESTING.md |
| Metric names | crates/telemetry/src/definitions.rs | OBSERVABILITY.md |
| Info section names | crates/telemetry/src/status.rs | OBSERVABILITY.md |
| Default config values | Config struct defaults | CONFIGURATION.md |
These are cases where the code is clearly correct and the doc is stale:
frogdb-lua, code has frogdb-scripting → fix docedition = "2021", Cargo.toml has "2024" → fix docthiserror = "1", Cargo.toml has "2" → fix doccrates/lua/, actual path is crates/scripting/ → fix docThese require human judgment:
Ambiguity presentation format:
REVIEW NEEDED: [brief description]
Doc (file:line): "[quoted text from doc]"
Code (file:line): [what the code actually shows]
Assessment: [your analysis of what likely happened]
Options:
A) Update doc to match code
B) Keep doc as-is (aspirational spec)
C) Something else — please describe
FIXED: [description]
File: [path:line]
Was: [old text]
Now: [new text]
Use the ambiguity presentation format above.
Audit Summary
─────────────
Checked: [N] assertions across [M] files
Fixed: [X] (auto-applied)
Review: [Y] (need your input)
Clean: [Z] (no drift found)
| File | When to Read |
|---|---|
references/doc-map.md | Change-triggered mode: map changed code → affected docs |
references/checkable-assertions.md | Audit mode: systematic checklist of verifiable claims |
Read these files at the start of the relevant mode. They contain pre-computed mappings that avoid scanning all 50+ docs for every check.
In scope:
website/src/content/docs/architecture/*.md (internals/contributor docs)website/src/content/docs/operations/*.md (operator docs)website/src/content/docs/guides/*.md (user docs)CLAUDE.md (project instructions)README.md (project overview)AGENTS.md (agent guidelines)testing/jepsen/README.md (Jepsen test docs)Out of scope:
todo/** — these are explicitly unimplemented/future work.claude/skills/*/SKILL.md — maintained by the skill-creator skillDefer to other skills:
/db-architect/checkRun build checks, linting, formatting, and tests for the FrogDB project using the Justfile. Handles smart scoping (targeting specific crates based on what changed), sccache troubleshooting, nextest configuration, and all test types (unit, integration, proptest, Shuttle concurrency, Turmoil simulation). Use this skill whenever the user asks to check, lint, format, test, verify, or validate their code changes — even partial requests like "run tests" or "does this compile". Also use when builds fail with sccache errors or test timeouts.
Manage the self-hosted GitHub Actions runner (rebuild image, restart container, check status/logs, troubleshoot). Use this skill whenever runner config files are modified (.github/runner/Dockerfile, docker-compose.yml), when the user asks about the CI runner, or when CI jobs fail with runner-related errors. Proactively suggest rebuilding when you notice changes to runner configuration during a session.
Manage the FrogDB development server lifecycle: start, restart, and stop. Start the server with continuous low-volume background traffic for testing metrics, debug pages, logs, and observability features. Automatically kills any existing dev server before starting a new one (one instance per worktree). Use when the user asks to start/stop/restart the dev server, run the server for development, test the debug UI, or when you've edited server code and need to restart to pick up changes. Also use after editing HTML/CSS/JS assets under frogdb-server/crates/debug/assets/ since rust-embed bakes them at compile time.
Benchmark FrogDB: standalone load testing (memtier_benchmark), comparative benchmarks against Redis/Valkey/Dragonfly, cluster-mode scaling, Criterion micro-benchmarks, durability mode comparison, and result interpretation with architectural context. Use when the user asks to benchmark, compare performance, run load tests, measure throughput/latency, compare against Redis/Valkey/Dragonfly, run Criterion benchmarks, test different durability modes, or understand why one database outperforms another.
Profile FrogDB performance: CPU sampling (samply), async flamegraphs (tracing-flame), causal profiling (tokio-coz), memory profiling (heaptrack), and always-on metrics (tokio-metrics). Use when the user asks to profile, investigate performance, generate flamegraphs, do causal/memory profiling, or analyze CPU/async hotspots. For benchmarking, load testing, or comparing against Redis/Valkey/Dragonfly, use the `/benchmark` skill instead.
Architectural design and implementation planning for FrogDB. Produces a design rationale and implementation plan written to the plan mode plan file. Invoke for any non-trivial change: new commands, new subsystems, cross-crate feature additions, concurrency changes, persistence changes, protocol changes, replication impacts, or any work touching more than one crate. Also use when the user asks about architecture, component design, request flows, dispatch mechanisms, or tradeoffs. Even for simpler changes like adding a single command, use this skill to ensure the right execution strategy, WAL strategy, and flags are chosen.