From fceed18e3d6b2fa06e2442787eedc6018987d855 Mon Sep 17 00:00:00 2001 From: Ruoshi Date: Wed, 11 Nov 2026 17:46:12 +0000 Subject: [PATCH] docs: cite AGENTS.md instead of CLAUDE.md for repo guidance (#171) PR #170 moved the architecture overview, design patterns, the no-materialization rule and the build commands from CLAUDE.md into AGENTS.md; CLAUDE.md now only includes AGENTS.md. Repoint the ADR Sources/notes lines (0001, 0005, 0007, 0012 and their .cn.md counterparts) and MODULE_GUIDE's build-commands line to AGENTS.md, and use the section names AGENTS.md actually has. ADR decisions are unchanged; ADR 0011 keeps its separately tracked stale-wording note. --- docs/MODULE_GUIDE.md | 2 +- docs/adr/0001-sequence-oriented-data-model.cn.md | 2 +- docs/adr/0001-sequence-oriented-data-model.md | 2 +- docs/adr/0005-no-materialization-rule.cn.md | 4 ++-- docs/adr/0005-no-materialization-rule.md | 4 ++-- docs/adr/0007-lambda-dsl-schemaproxy.cn.md | 2 +- docs/adr/0007-lambda-dsl-schemaproxy.md | 2 +- docs/adr/0012-rust-thin-shell-python-mixins.cn.md | 2 +- docs/adr/0012-rust-thin-shell-python-mixins.md | 2 +- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/MODULE_GUIDE.md b/docs/MODULE_GUIDE.md index faade9ed..721af688 100644 --- a/docs/MODULE_GUIDE.md +++ b/docs/MODULE_GUIDE.md @@ -458,7 +458,7 @@ When in doubt, find the most specific relevant test first, then trace into imple ## Build and Verification Commands -Common commands from `CLAUDE.md`: +Common commands from `AGENTS.md`: ```bash maturin develop diff --git a/docs/adr/0001-sequence-oriented-data-model.cn.md b/docs/adr/0001-sequence-oriented-data-model.cn.md index 3395c011..9741eeb7 100644 --- a/docs/adr/0001-sequence-oriented-data-model.cn.md +++ b/docs/adr/0001-sequence-oriented-data-model.cn.md @@ -36,4 +36,4 @@ pandas/SQL 式的集合语义被否决为核心模型。`README.md` 的 FAQ 明 - `docs/USER_MODEL.cn.md`: “LTSeq 不是什么” - `docs/DESIGN_SUMMARY.cn.md`: 概览 - `README.md`: Design Philosophy、FAQ -- `CLAUDE.md`: Architecture Overview +- `AGENTS.md`: Architecture overview diff --git a/docs/adr/0001-sequence-oriented-data-model.md b/docs/adr/0001-sequence-oriented-data-model.md index a6f31a22..c092466f 100644 --- a/docs/adr/0001-sequence-oriented-data-model.md +++ b/docs/adr/0001-sequence-oriented-data-model.md @@ -36,4 +36,4 @@ Set-based semantics as in pandas/SQL were rejected as the core model. The `READM - `docs/USER_MODEL.md`: "What LTSeq Is Not" - `docs/DESIGN_SUMMARY.md`: §Overview - `README.md`: Design Philosophy, FAQ -- `CLAUDE.md`: Architecture Overview +- `AGENTS.md`: Architecture overview diff --git a/docs/adr/0005-no-materialization-rule.cn.md b/docs/adr/0005-no-materialization-rule.cn.md index 1f035299..924bc1c2 100644 --- a/docs/adr/0005-no-materialization-rule.cn.md +++ b/docs/adr/0005-no-materialization-rule.cn.md @@ -17,7 +17,7 @@ 该规则并不（也无法）覆盖所有返回表的 API。以下操作因设计或当前实现而物化： -**正确性所需的例外**（记录于 `CLAUDE.md`；不是捷径）： +**正确性所需的例外**（记录于 `AGENTS.md`；不是捷径）： 1. **物理位置操作**（`rvs`、`step`、带键 `distinct`）在分配行位置前，先把表快照为单个按序分区（collect → read_batch），因为对惰性多分区计划做无序/分区窗口不会保持输入顺序（`set_ops.rs::snapshot_single_partition`）。 2. **`fold()`** 逐行运行用户提供的 Python 回调 `fn(state, row)`；任意 Python 无法表达为 DataFusion 计划，逐行路径（`to_arrow()` → Python 行 → 累加 → 对同一 Arrow 表追加新列后 `from_arrow()`）是固有属性。docstring 标明这是非惰性慢路径（对比 Polars `cumulative_eval`）。 @@ -42,7 +42,7 @@ ## 来源 -- `CLAUDE.md`: No Materialization Rule（两个正确性例外） +- `AGENTS.md`: Key design patterns, No materialization rule（两个正确性例外） - `docs/ARCHITECTURE.cn.md`: No-Materialization Rule、设计目标 #4 - `docs/DESIGN_SUMMARY.cn.md`: §5.4、§7.4 - `docs/USER_MODEL.cn.md`: 物化模型 diff --git a/docs/adr/0005-no-materialization-rule.md b/docs/adr/0005-no-materialization-rule.md index a664b427..df8552b1 100644 --- a/docs/adr/0005-no-materialization-rule.md +++ b/docs/adr/0005-no-materialization-rule.md @@ -17,7 +17,7 @@ Benchmarking and design experience identified materialization as "the main archi The rule does not (and cannot) cover every table-returning API. The following operations materialize by design or by current implementation: -**Correctness-required exceptions** (documented in `CLAUDE.md`; not shortcuts): +**Correctness-required exceptions** (documented in `AGENTS.md`; not shortcuts): 1. **Physical-position ops** (`rvs`, `step`, keyed `distinct`) snapshot the table into a single in-order partition (collect → read_batch) before assigning row positions, because an unordered/partitioned window over a lazy multi-partition plan does not preserve input order (`set_ops.rs::snapshot_single_partition`). 2. **`fold()`** runs a user-supplied Python callback `fn(state, row)` per row; arbitrary Python cannot be a DataFusion plan, so the row-wise path (`to_arrow()` → Python rows → accumulate → `from_arrow()` of the same Arrow table plus the new column) is inherent. Its docstring flags it as a non-lazy slow path (compare Polars `cumulative_eval`). @@ -42,7 +42,7 @@ These live on the Rust side (Arrow batches, no Python row round-trips), but they ## Sources -- `CLAUDE.md`: No Materialization Rule (the two correctness exceptions) +- `AGENTS.md`: Key design patterns, No materialization rule (the two correctness exceptions) - `docs/ARCHITECTURE.md`: No-Materialization Rule, Design Goals #4 - `docs/DESIGN_SUMMARY.md`: §5.4, §7.4 - `docs/USER_MODEL.md`: Materialization Model diff --git a/docs/adr/0007-lambda-dsl-schemaproxy.cn.md b/docs/adr/0007-lambda-dsl-schemaproxy.cn.md index 9b5d573a..54e89a1c 100644 --- a/docs/adr/0007-lambda-dsl-schemaproxy.cn.md +++ b/docs/adr/0007-lambda-dsl-schemaproxy.cn.md @@ -33,4 +33,4 @@ API 应当读起来像 Python（`t.filter(lambda r: r.age > 18)`），又不付 - `docs/USER_MODEL.cn.md`: 核心心智模型 #4、表达式模型 - `docs/MODULE_GUIDE.cn.md`: 表达式子系统导览 - `docs/api.cn.md`: §0、§11 -- `CLAUDE.md`: Expression Transpilation +- `AGENTS.md`: Key design patterns, Expression transpilation diff --git a/docs/adr/0007-lambda-dsl-schemaproxy.md b/docs/adr/0007-lambda-dsl-schemaproxy.md index a26aa6a7..38b972ba 100644 --- a/docs/adr/0007-lambda-dsl-schemaproxy.md +++ b/docs/adr/0007-lambda-dsl-schemaproxy.md @@ -33,4 +33,4 @@ Capture, serialize, transpile: - `docs/USER_MODEL.md`: Core Mental Model #4, Expression Model, Common Mistakes - `docs/MODULE_GUIDE.md`: Expression Subsystem Tour, transpiler tour - `docs/api.md`: §0, §11 -- `CLAUDE.md`: Expression Transpilation +- `AGENTS.md`: Key design patterns, Expression transpilation diff --git a/docs/adr/0012-rust-thin-shell-python-mixins.cn.md b/docs/adr/0012-rust-thin-shell-python-mixins.cn.md index cac2bb90..0a57805c 100644 --- a/docs/adr/0012-rust-thin-shell-python-mixins.cn.md +++ b/docs/adr/0012-rust-thin-shell-python-mixins.cn.md @@ -25,7 +25,7 @@ ## 来源 -- `CLAUDE.md`: Key Design Patterns（PyO3 单 `#[pymethods]` 约束、mixin 组合） +- `AGENTS.md`: Key design patterns（PyO3 单 `#[pymethods]` 约束、mixin 组合） - `docs/ARCHITECTURE.cn.md`: PyO3 边界设计、Rust/Python 包结构 - `docs/DESIGN_SUMMARY.cn.md`: §1.3、§1.4 - `docs/MODULE_GUIDE.cn.md`: `src/lib.rs`、模块导览 diff --git a/docs/adr/0012-rust-thin-shell-python-mixins.md b/docs/adr/0012-rust-thin-shell-python-mixins.md index 9177b405..3a70d822 100644 --- a/docs/adr/0012-rust-thin-shell-python-mixins.md +++ b/docs/adr/0012-rust-thin-shell-python-mixins.md @@ -25,7 +25,7 @@ Both sides of the boundary risk monolith files: PyO3 allows only **one `#[pymeth ## Sources -- `CLAUDE.md`: Key Design Patterns (PyO3 single `#[pymethods]` constraint, mixin composition) +- `AGENTS.md`: Key design patterns (PyO3 single `#[pymethods]` constraint, mixin composition) - `docs/ARCHITECTURE.md`: PyO3 Boundary Design, Rust/Python Package Structure - `docs/DESIGN_SUMMARY.md`: §1.3, §1.4 - `docs/MODULE_GUIDE.md`: `src/lib.rs`, module tours