From 88811466f286371eae61f17babbd39ea44fc7e5c Mon Sep 17 00:00:00 2001 From: Hare Date: Mon, 12 Oct 2026 15:54:18 +0900 Subject: [PATCH] docs: streamline agent guidance and standardize rustdoc links --- AGENTS.md | 79 +++++-------------------- KNOWN_ISSUES.md | 8 --- crates/flow/README.md | 8 +-- crates/mcp/README.md | 2 +- crates/tools/README.md | 8 +-- crates/tui/README.md | 6 +- crates/worker-runtime/README.md | 2 +- crates/worker/README.md | 10 ++-- crates/yoi/README.md | 5 +- docs/README.md | 2 +- docs/development/validation.md | 10 +++- docs/development/work-items.md | 2 +- docs/principle/authority-and-history.md | 4 +- 13 files changed, 48 insertions(+), 98 deletions(-) delete mode 100644 KNOWN_ISSUES.md diff --git a/AGENTS.md b/AGENTS.md index 56a8f46a1..b1e2519d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,71 +1,22 @@ -すでにシステムのドッグフーディングに成功しており、ブラウザ/TUI Client/backend/runtimeの分離とチームスペースとしてのworkspaceの実装を進めている。 - -## 文書と設計 - -文書の追加・変更・削除は[文書管理規則](docs/README.md)に従う。設計理由は所有するRust module・itemのrustdocへ置き、crate READMEは短い概要と参照にする。利用ガイドや設定説明は追加しない。 +# 開発時の入口 変更量を最小にするために設計を歪めたり、不必要な後方互換性を作ったりしない。長期的な保守性と型安全性を優先する。 -### 状態契約の命名・競合制御 +## 作業条件に応じて読む規則 -- `revision` という名前を、大小文字や複合語を含め、新しい型・フィールド・変数・API・DB列・文書に導入しない。 -- 不透明な更新番号を別の汎用名へ言い換えて済ませない。何を、どの根拠と比較し、どの操作の前／中／後に確認するかを、コードの名前と境界処理で示す。 -- 到着順、操作時刻、先勝ち／後勝ちだけで成立する処理はそれで実装する。内容の一致、鍵の一致、同じ操作の再送、同じ接続の生存期間を確認する必要がある場合は、その対象を明示し、順序や時刻だけでは足りない理由を残す。 -- 旧保存データを読むための綴りは現行契約と分離する。削除によるデータ喪失を避けるために残す場合も、必要な行と理由を明示して検査対象にする。文字列分割・符号化や広いディレクトリ除外で検査を逃れない。 -- 完了前に `env -u LD_LIBRARY_PATH deno run --allow-read --allow-run=git tools/check-state-contract-names.ts` を実行する。例外一覧を機械的に増やして合格させない。 +該当する作業の前に、次の文書を読み、その規則に従う。 -### LLM コンテキストの加工原則 +- 文書・説明コメントを追加、変更、削除する → [文書管理規則](docs/README.md) +- 正本、権限、状態の競合制御、LLM入力・履歴を扱う → [正本・権限・実行の原則](docs/principle/authority-and-history.md) +- 永続操作、外部副作用、再試行・復旧を設計する → [永続操作の原則](docs/principle/durable-operations.md) +- テストを追加・変更する → [テスト設計規則](docs/development/rust-testing-strategy.md) +- 変更を検証する・作業を完了する → [検証規則](docs/development/validation.md) +- 保存schemaやmigrationを変更する → [保存schema変更の規則](docs/development/workspace-schema-migrations.md) +- Webの画面・操作を設計する → [UX設計](docs/principle/ux-design.md)・[Design Language](docs/principle/design-language.md)。描画を変更したら[目視確認規則](docs/development/ui-ux/visual-review.md)にも従う。 +- Ticket・Objective・作業記録を扱う → [作業記録と判断の規則](docs/development/work-items.md) +- 稼働環境に関わる作業や、開発中の障壁を報告する → [ドッグフーディングの安全規則](docs/development/dogfooding.md) -[正本・権限・履歴の原則](docs/principle/authority-and-history.md)に従う。LLM入力へ影響する情報は履歴へ先に確定し、永続化形式から再構成できるようにする。圧縮の保証と限界は所有moduleに記述し、実測に基づいて変更する。 +## 常に守ること ---- - -## 検証 - -テストを追加・変更する前に、必ず[テスト設計規則](docs/development/rust-testing-strategy.md)を読み、その規則に従うこと。 - -開発中は、変更した契約を証明する最小の target / filter から実行する。 - -```sh -cargo test -p --lib -cargo test -p --test -``` - -完了前には、workspace rootで必ず`cargo check`を実行する。rootの`cargo check`は -`default-members`に含まれるTUIやServerを含む通常のcompile closureを確認するため、公開型の -変更ごとにLLMがreverse dependencyを推測して`-p`を列挙する運用にはしない。 - -```sh -cargo check -cargo test -p -cargo fmt --all -- --check -git diff --check HEAD -``` - -変更したcrate全体のtestに加え、影響するfeature構成やtest-only targetがある場合は、その検証を -追加する。`cargo check`はtestを実行せず、通常有効でないfeatureまでは確認しないため、semanticな -証明とfeature境界の検証はtargeted test/checkで補う。 - -workspace全体のtest、`--all-targets`、E2E、Nix/Docker buildなどの重い検証は、変更した境界を -通常のroot checkと狭い検証では証明できない場合や、明示的に要求された場合に選ぶ。実行した検証が -何を証明するのかを意識し、広い検証を形式的に回すだけにしない。 - ---- - -## ドッグフーディング時の Ticket 境界 - -Yoi Worker で作業する場合、Ticket の authority・ライフサイクル・操作方法は Yoi -system instructions と、その Worker に提供された typed Ticket tools に従うこと。 - -Codex など typed Ticket tools が提供されていないクライアントでは、`yoi ticket` -CLI や保存先の直接操作で Ticket tools を代替しないこと。Ticket の作成・更新は -Yoi Worker に委ねる。 - ---- - -YoiでYoiを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。 - ---- - -絶対に自身が動作しているプロセスを止めないこと。 -マージ後のドッグフーディング環境の更新は必ずユーザーの操作で行う。 +- 自身を実行しているプロセスを停止しない。マージ後の稼働環境の更新は利用者が行う。 +- Ticket操作は提供されたtyped toolsとsystem instructionsに従い、CLIや保存先の直接編集で代替しない。 diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md deleted file mode 100644 index 346a58e3e..000000000 --- a/KNOWN_ISSUES.md +++ /dev/null @@ -1,8 +0,0 @@ -# Known Issues - -Ticket を切るほどではないが、次に近所を触るときに合わせて拾いたい小粒な所見の置き場。 - -- `crates/worker/src/controller.rs:1453-1461` — `worker_error_code` で `WorkerError::WorkflowResolve(_) => InvalidRequest` が post-commit な resolve エラー (`KnowledgeNotFound` 等) にも適用される。意味論的には妥当方向だが、resolve 系のエラー粒度を分けたくなったタイミングで再評価。 -- `crates/session-store/src/fs_store.rs:200-210` — `FsStore::read_entry_count` が `fs::read_to_string` で全文ロードしてから行数カウントするため O(n)。`ensure_head_or_fork` は run-start でしか呼ばれず現状は許容範囲だが、長期セッションが普通になった時点で `\n` バイト数の cheap count か末尾 seek に置き換える。 -- `crates/session-store/src/segment.rs:143-172` `ensure_head_or_fork` (free fn, test 専用・本番 caller ゼロ) と `crates/worker/src/worker.rs:2032` `Worker::ensure_segment_head` (本番 inline) に live auto-fork の検知 + forked_from 記録が二重実装されている。entry-hash-abolish 以前からの重複で、両方独立にテスト済みだが drift 必至。session-store 側を本番から呼ぶ形に寄せるか free fn を畳むかは要設計判断。Worker state / fork 周辺を次に触るときに統合を検討。 -- `crates/worker/src/worker.rs` / `crates/worker/src/spawn/registry.rs:84-174` — restore 時の spawned child prune/reclaim が Worker restore path と spawned registry load path の両方に残っている。現状は安全側の重複チェックだが、Worker state / spawned registry 周辺を次に触るときに責務境界を再整理。 diff --git a/crates/flow/README.md b/crates/flow/README.md index 517785458..297b5659d 100644 --- a/crates/flow/README.md +++ b/crates/flow/README.md @@ -4,7 +4,7 @@ ## Main entry points -- [`compile_flow_source`](src/definition.rs): Source evaluation and graph validation. -- [`FlowSelector`](src/selector.rs) / [`ResolvedFlowSource`](src/selector.rs): Explicit source identity and immutable snapshots. -- [`FlowRuntimeState`](src/coordinator.rs): Instances, transition attempts, and ordered events. -- [`builtin_flow_source`](src/builtin.rs): Read-only catalog of embedded sources. +- [`compile_flow_source`]: Source evaluation and graph validation. +- [`FlowSelector`] / [`ResolvedFlowSource`]: Explicit source identity and immutable snapshots. +- [`FlowRuntimeState`]: Instances, transition attempts, and ordered events. +- [`builtin_flow_source`]: Read-only catalog of embedded sources. diff --git a/crates/mcp/README.md b/crates/mcp/README.md index 4d8b6faa7..dd50e8b0c 100644 --- a/crates/mcp/README.md +++ b/crates/mcp/README.md @@ -4,4 +4,4 @@ ## Main entry points -- [`stdio`](src/stdio.rs): Server launch configuration resolution, bounded responses, diagnostics, and shutdown. +- [`stdio`]: Server launch configuration resolution, bounded responses, diagnostics, and shutdown. diff --git a/crates/tools/README.md b/crates/tools/README.md index 5003eb332..c59fcfd46 100644 --- a/crates/tools/README.md +++ b/crates/tools/README.md @@ -4,7 +4,7 @@ ## Main entry points -- [`core_builtin_tools`](src/lib.rs) / [`routed_builtin_tools`](src/lib.rs): registration by provider capability and connection resolution. -- [`checkout`](src/checkout.rs): shared handling for route-bound native operations and regular Tools. -- [`tracker`](src/tracker.rs): read hashes and change tracking per connection generation. -- [`view_image`](src/view_image.rs): bounded byte retrieval and image detection. +- [`core_builtin_tools`] / [`routed_builtin_tools`]: registration by provider capability and connection resolution. +- [`checkout`]: shared handling for route-bound native operations and regular Tools. +- [`tracker`]: read hashes and change tracking per connection generation. +- [`view_image`]: bounded byte retrieval and image detection. diff --git a/crates/tui/README.md b/crates/tui/README.md index 34d916092..479456cca 100644 --- a/crates/tui/README.md +++ b/crates/tui/README.md @@ -4,7 +4,5 @@ ## Implementation entry points -- [`launch`] / [`LaunchMode`] — typed launch requests and terminal restoration. -- `src/app.rs`: display state built from protocol snapshots and events. -- `src/input.rs` / `src/composer_history.rs`: typed input and local editing history. -- `src/console/`: connection, input-event, and attachment-staging management. +- [`launch`] — Console and Dashboard execution with terminal restoration. +- [`LaunchOptions`] / [`LaunchMode`] — typed connection and launch requests. diff --git a/crates/worker-runtime/README.md b/crates/worker-runtime/README.md index 22b93b028..4984c2e18 100644 --- a/crates/worker-runtime/README.md +++ b/crates/worker-runtime/README.md @@ -4,7 +4,7 @@ Manages Worker creation, stopping, and Restore, execution connections within the ## Reference index -- [`Runtime`](crate::Runtime): lifecycle operation acceptance, Workspace boundaries, and execution connections. +- [`Runtime`]: lifecycle operation acceptance, Workspace boundaries, and execution connections. - [`execution`] — execution backends and operation-specific results. - [`working_directory`] — repository materialization, session resources, and safe deletion. - [`workspace_issuer`] — Workspace signature verification and replay prevention. diff --git a/crates/worker/README.md b/crates/worker/README.md index 5e55bb88e..7f85b8a2e 100644 --- a/crates/worker/README.md +++ b/crates/worker/README.md @@ -4,8 +4,8 @@ ## Main entry points -- [`Worker`](src/worker.rs): Input admission, execution, and Session restoration. -- [`controller`](src/controller.rs): Worker control and protocol intake. -- [`feature`](src/feature.rs): Feature declarations, registration, and structured invocation. -- [`wip`](src/wip.rs): WIP namespaces, native/compatibility projections, and the Client/Host boundary. -- [`spawn`](src/spawn/mod.rs): Delegation and control of parent-owned Internal SubWorkers. +- [`Worker`]: Input admission, execution, and Session restoration. +- [`controller`]: Worker control and protocol intake. +- [`feature`]: Feature declarations, registration, and structured invocation. +- [`wip`]: WIP namespaces, native/compatibility projections, and the Client/Host boundary. +- [`spawn`]: Delegation and control of parent-owned Internal SubWorkers. diff --git a/crates/yoi/README.md b/crates/yoi/README.md index e7888d00e..35983d08c 100644 --- a/crates/yoi/README.md +++ b/crates/yoi/README.md @@ -4,7 +4,6 @@ ## Implementation entry points -- `src/main.rs`: product command parsing and dispatch to launch targets. -- `src/cli_connection.rs`: per-command connection requirements and target resolution. -- `src/workspace_bootstrap.rs`: Workspace creation and Backend routing records. +Command dispatch, connection selection, and Workspace bootstrap are binary-internal. The library exposes: + - [`workdir_share`] — sharing existing Workdirs. diff --git a/docs/README.md b/docs/README.md index 3252caf0c..79510c29e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ - `principle/`：複数の実装に共通する設計原則。判断が競合したときの基準と、その理由を書く。個別の処理手順やデータ構造は置かない。 - `development/`：テスト設計、検証、レビューなど、開発を続けるための規則。製品の操作手順や環境設定の説明は置かない。 - `report/`：問題発生時の報告。試みた操作、観測した事実、影響、原因の確度、未解決事項を記録する。過去の報告は現行仕様の根拠にせず、当時の記録として蓄積できる。 -- Rustのcrate README：責務と非責務を短く示し、主要moduleへの参照を置く。各crateの`lib.rs`は`#![doc = include_str!("../README.md")]`でREADMEをcrateドキュメントとして使う。 +- Rustのcrate README：責務と非責務を短く示し、主要moduleへの参照を置く。各crateの`lib.rs`は`#![doc = include_str!("../README.md")]`でREADMEをcrateドキュメントとして使い、参照はrustdocのintra-doc linkに統一する。リンク先は公開ドキュメントに存在するmodule・itemとし、リンクのために実装の公開範囲を広げない。 - Rustのmodule・itemドキュメント：所有境界、状態遷移、失敗時の保証と限界、非自明な判断理由を書く。API一覧や実装の逐語説明は繰り返さない。 WebなどRust以外の実装に固有の理由は、そのソースのmodule・型・処理に付くコメントで管理する。無関係なRust crateへ移さず、実装説明の別冊も増やさない。複数の画面・部品の設計判断に使うDesign LanguageやUX規則は文書として維持し、個別実装の説明と区別する。 diff --git a/docs/development/validation.md b/docs/development/validation.md index 768630eb2..f0eedabe5 100644 --- a/docs/development/validation.md +++ b/docs/development/validation.md @@ -15,7 +15,7 @@ cargo test -p --lib cargo test -p --test ``` -完了前は[AGENTS.md](../../AGENTS.md)に従ってrootのcompile closureと変更crate全体を確認する。 +完了前にはworkspace rootで必ず`cargo check`を実行し、TUI・Serverを含む通常のcompile closureと変更crate全体を確認する。公開型の変更ごとにreverse dependencyを推測して`-p`を列挙する運用にはしない。 ```sh cargo check @@ -28,6 +28,14 @@ git diff --check HEAD Workspace全体、`--all-targets`、Nix/Dockerなどの重い検証は、変更した境界を狭い検証では確認できない場合か、明示的に求められた場合に選ぶ。既存の無関係なformat差分を混ぜない。公開APIや生成元を変えた場合は、所有する生成処理と差分検査で生成物との一致を確認する。 +## 状態契約の命名検査 + +完了前に次を実行する。例外一覧を機械的に増やして合格させず、必要な保存互換・検証・禁止規則の記述だけを理由付きで扱う。 + +```sh +env -u LD_LIBRARY_PATH deno run --allow-read --allow-run=git tools/check-state-contract-names.ts +``` + ## Webとレビュー 描画結果が変わるWeb UI変更には、type check・testに加えて実装者自身の[目視確認](ui-ux/visual-review.md)を必要とする。画像の生成、HTTP成功、後段Reviewerへの委託だけでは代替できない。 diff --git a/docs/development/work-items.md b/docs/development/work-items.md index 820fa6d66..ec094dd61 100644 --- a/docs/development/work-items.md +++ b/docs/development/work-items.md @@ -12,7 +12,7 @@ Ticketには、利用者の意図と、それに対して判定できる成果 ## 正本の確認と成果の報告 -実装・routing・レビュー・終了の判断前には、現行Ticketと必要な関連記録を読む。通知、要約、過去の実装報告を現行の要求や承認の証拠にしない。Worker内の操作は、提供されたtyped toolsとsystem instructionsに従う。CLIや保存先の直接編集で欠けた権限を代替しない。 +実装・routing・レビュー・終了の判断前には、現行Ticketと必要な関連記録を読む。通知、要約、過去の実装報告を現行の要求や承認の証拠にしない。Worker内の操作は、提供されたtyped toolsとsystem instructionsに従う。CLIや保存先の直接編集で欠けた権限を代替しない。typed Ticket toolsのないクライアントでは、Ticketの作成・更新をYoi Workerへ委ねる。 成果には、実際の変更、検証結果、未確認事項、判断に必要な証拠を残す。すべての作業にコメントやartifactを義務付けず、利用者が必要とする返却方法を選ぶ。長い調査結果、生ログ、秘密情報はTicket本文へ転載しない。 diff --git a/docs/principle/authority-and-history.md b/docs/principle/authority-and-history.md index b096eb1a5..717b9e6a5 100644 --- a/docs/principle/authority-and-history.md +++ b/docs/principle/authority-and-history.md @@ -26,6 +26,8 @@ LLMの生成に影響する入力は、リクエストへ加える前に履歴 作業の結論、レビュー判断、コード統合、Worker停止、記録の保持、接続解除、資源削除は別の判断である。一つの成功を別の操作の許可として流用しない。自動的に連動させる場合は、その責任を持つ操作として条件と結果を定義する。 -競合確認では、何を、どの観測と比較し、どの操作の前後で検査するかを名前と処理で示す。到着順や時刻で足りる処理に不透明な更新番号を加えない。内容の一致、同じ操作の再送、鍵の一致、接続の生存期間を確認する場合は、それぞれを識別する根拠を使う。 +競合確認では、何を、どの観測と比較し、どの操作の前／中／後に検査するかを名前と処理で示す。到着順、時刻、先勝ち・後勝ちで足りる処理に不透明な更新番号を加えず、別の汎用名への言い換えでも済ませない。内容の一致、同じ操作の再送、鍵の一致、接続の生存期間を確認する場合は、それぞれを識別する根拠を使い、順序や時刻だけでは足りない理由を残す。 + +旧保存データを読むために必要な綴りは現行契約と分離し、残す行とデータ保持上の理由を明示して検査対象にする。文字列分割・符号化や広いディレクトリ除外で命名検査を逃れない。 個別の永続操作と再試行の判断は[永続操作の原則](durable-operations.md)に従う。具体的な認証、保存、復旧の仕組みは所有moduleのドキュメントに置く。