docs: streamline agent guidance and standardize rustdoc links
This commit is contained in:
@@ -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 <crate> --lib <test-or-module-filter>
|
||||
cargo test -p <crate> --test <test-target> <test-filter>
|
||||
```
|
||||
|
||||
完了前には、workspace rootで必ず`cargo check`を実行する。rootの`cargo check`は
|
||||
`default-members`に含まれるTUIやServerを含む通常のcompile closureを確認するため、公開型の
|
||||
変更ごとにLLMがreverse dependencyを推測して`-p`を列挙する運用にはしない。
|
||||
|
||||
```sh
|
||||
cargo check
|
||||
cargo test -p <changed-crate>
|
||||
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や保存先の直接編集で代替しない。
|
||||
|
||||
@@ -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 周辺を次に触るときに責務境界を再整理。
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
+1
-1
@@ -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規則は文書として維持し、個別実装の説明と区別する。
|
||||
|
||||
@@ -15,7 +15,7 @@ cargo test -p <crate> --lib <test-or-module-filter>
|
||||
cargo test -p <crate> --test <test-target> <test-filter>
|
||||
```
|
||||
|
||||
完了前は[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への委託だけでは代替できない。
|
||||
|
||||
@@ -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本文へ転載しない。
|
||||
|
||||
|
||||
@@ -26,6 +26,8 @@ LLMの生成に影響する入力は、リクエストへ加える前に履歴
|
||||
|
||||
作業の結論、レビュー判断、コード統合、Worker停止、記録の保持、接続解除、資源削除は別の判断である。一つの成功を別の操作の許可として流用しない。自動的に連動させる場合は、その責任を持つ操作として条件と結果を定義する。
|
||||
|
||||
競合確認では、何を、どの観測と比較し、どの操作の前後で検査するかを名前と処理で示す。到着順や時刻で足りる処理に不透明な更新番号を加えない。内容の一致、同じ操作の再送、鍵の一致、接続の生存期間を確認する場合は、それぞれを識別する根拠を使う。
|
||||
競合確認では、何を、どの観測と比較し、どの操作の前／中／後に検査するかを名前と処理で示す。到着順、時刻、先勝ち・後勝ちで足りる処理に不透明な更新番号を加えず、別の汎用名への言い換えでも済ませない。内容の一致、同じ操作の再送、鍵の一致、接続の生存期間を確認する場合は、それぞれを識別する根拠を使い、順序や時刻だけでは足りない理由を残す。
|
||||
|
||||
旧保存データを読むために必要な綴りは現行契約と分離し、残す行とデータ保持上の理由を明示して検査対象にする。文字列分割・符号化や広いディレクトリ除外で命名検査を逃れない。
|
||||
|
||||
個別の永続操作と再試行の判断は[永続操作の原則](durable-operations.md)に従う。具体的な認証、保存、復旧の仕組みは所有moduleのドキュメントに置く。
|
||||
|
||||
Reference in New Issue
Block a user