mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-26 08:18:18 +00:00
Zhengchao An
d1db9a10cd
Agent-instruction and architecture docs had drifted from the code: - CLAUDE.md: slim to commands + pointers; fix wrong claim that `make pre-commit` is the full pre-PR gate (that is `make pre-pr`); drop stale pre-#3929 file paths and merged bug narratives - AGENTS.md: drop dead `rust-refactor-helper` skill rule and the hand-maintained (already stale) scoped-AGENTS index; link architecture docs from Sources of Truth - .github/AGENTS.md: replace the outdated copied CI command matrix with a pointer to ci.yml - crates/AGENTS.md: merge duplicated Testing sections - ARCHITECTURE.md: resolve the utils->config contradiction (edges are removed), mark volatile counts as snapshots, fix a bad path - docs/architecture: add README router; move one-shot plans/trackers (rebalance-decommission phases, migration-progress ledger, PR template) to docs/superpowers/plans with archive headers; fix stale source paths in kept inventories (core/sets.rs, core/pools.rs, store/mod.rs, startup_* split from #3671) - docs/operations/tier-ilm-debugging.md: extracted tier debugging playbook with corrected paths - scripts/check_doc_paths.sh: new guard failing pre-commit/pre-pr when instruction/architecture docs reference nonexistent file paths - .claude/skills: add tier-debug and arch-checks repo skills; .gitignore now keeps .claude/skills and docs/operations committable Verification: ./scripts/check_doc_paths.sh, ./scripts/check_architecture_migration_rules.sh (both pass) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Architecture Documentation
Durable architecture reference for RustFS: migration guardrails, runtime contracts, boundary rules, and support matrices.
Two rules keep this directory healthy:
- Durable reference only. One-shot implementation plans, task trackers,
and PR templates live in
docs/superpowers/plans/and are archived there when their work closes. - No copies of other sources of truth. Crate lists come from
Cargo.toml, CI steps from.github/workflows/ci.yml, code structure from the code.scripts/check_doc_paths.shfails the pre-commit gate when a doc here references a file path that no longer exists.
Start here
- overview.md — migration baseline, phase order, core principles
CI-enforced core (required by scripts/check_architecture_migration_rules.sh)
- crate-boundaries.md — dependency direction, PR types, re-export contracts
- runtime-lifecycle.md — startup/shutdown sequencing, readiness guarantees
- readiness-matrix.md — request/dependency behavior, probe semantics
- storage-control-data-plane.md — storage API contracts, control-plane boundaries
- global-state-crate-split-plan.md — remaining global-state owners and split evaluation
- ecstore-module-split-plan.md — ECStore decomposition rules and facade contracts
Contracts & invariants
- placement-repair-invariants.md
- runtime-capability-contracts.md
- workload-admission-contracts.md
- background-controller-contract.md
- config-model-boundary-adr.md
- ecstore-layout-boundary.md
- decommission-compatibility.md
Support matrices (release-facing, keep current)
Inventories & baselines (snapshots that feed migration work)
- global-state-inventory.md
- ecstore-api-facade-inventory.md
- ecstore-config-consumer-inventory.md
- obs-ecstore-dependency-inventory.md
- background-services-inventory.md
- admin-route-action-snapshot.md
- startup-timeline.md
- scheduler-baseline.md
- profiling-numa-capability-inventory.md
- kms-development-defaults-inventory.md
- compat-cleanup-register.md
Historical plans and trackers (rebalance/decommission phases,
migration-progress ledger) were moved to
docs/superpowers/plans/ in 2026-07.