From 4f7a2e8a5246078ca456619e3419309f4ba2b5bd Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Sun, 3 May 2026 20:36:08 -0500 Subject: [PATCH] Improve readability in AGENTS.md (#8979) --- AGENTS.md | 71 ++++++++++++++++++++++++++----------------------------- 1 file changed, 33 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 89b9b604c4..286ecce432 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,54 +75,49 @@ ui/desktop/ # Electron app ## Rules -Test: Prefer tests/ folder, e.g. crates/goose/tests/ -Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate -Error: Use anyhow::Result -Provider: Implement Provider trait see providers/base.rs -MCP: Extensions in crates/goose-mcp/ -Server: Changes need just generate-openapi +- Test: Prefer tests/ folder, e.g. crates/goose/tests/ +- Test: When adding features, update goose-self-test.yaml, rebuild, then run `goose run --recipe goose-self-test.yaml` to validate +- Error: Use anyhow::Result +- Provider: Implement Provider trait see providers/base.rs +- MCP: Extensions in crates/goose-mcp/ +- Server: Changes need just generate-openapi ## Code Quality -Comments: Write self-documenting code - prefer clear names over comments -Comments: Never add comments that restate what code does -Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what" -Simplicity: Don't make things optional that don't need to be - the compiler will enforce -Simplicity: Booleans should default to false, not be optional -Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed) -Simplicity: Avoid overly defensive code - trust Rust's type system -Logging: Clean up existing logs, don't add more unless for errors or security events +- Comments: Write self-documenting code - prefer clear names over comments +- Comments: Never add comments that restate what code does +- Comments: Only comment for complex algorithms, non-obvious business logic, or "why" not "what" +- Simplicity: Don't make things optional that don't need to be - the compiler will enforce +- Simplicity: Booleans should default to false, not be optional +- Errors: Don't add error context that doesn't add useful information (e.g., `.context("Failed to X")` when error already says it failed) +- Simplicity: Avoid overly defensive code - trust Rust's type system +- Logging: Clean up existing logs, don't add more unless for errors or security events ## Ink / Terminal UI (ui/text) -Ink renders React to a fixed character grid — not a browser. Content that exceeds a Box's -dimensions is NOT clipped; it visually overflows into neighboring cells and breaks the layout. +- Ink renders React to a fixed character grid — not a browser. Content that exceeds a Box's dimensions is NOT clipped; it visually overflows into neighboring cells and breaks the layout. -Ink-Text: Never use `wrap="wrap"` inside a fixed-height Box — wrapped text can exceed the - Box height and bleed into adjacent components. Use `wrap="truncate"` and pre-truncate the - string to fit the available character budget (lines × width). -Ink-Layout: When changing card/cell dimensions, always recalculate how much content fits. - Account for borders (2 chars), padding, margins, and sibling elements when computing the - remaining space for dynamic text. -Ink-Overflow: Ink has no `overflow: hidden`. The only way to prevent overflow is to ensure - content never exceeds the container size — truncate text, limit list items, or cap height. -Ink-FlexGrow: Avoid `flexGrow={1}` on text containers inside fixed-height cards — the text - will try to fill available space but Ink won't clip it if it exceeds the boundary. -Ink-HeightBudget: When computing how many rows/items fit vertically, count EVERY line used - by headers, footers, margins, borders, and scroll indicators. Under-reserving vertical - space (e.g., `height - 8` when chrome actually uses 16 lines) causes Ink to squeeze out - margins between items, making borders collapse. Always audit the actual line count. -Ink-TrailingMargin: Don't apply `marginBottom` to the last item in a list — it wastes a - line and can push content out of the container. Use conditional margins or container `gap`. +- Ink-Text: Never use `wrap="wrap"` inside a fixed-height Box — wrapped text can exceed the Box height and bleed into adjacent components. Use `wrap="truncate"` and pre-truncate the string to fit the available character budget (lines × width). + +- Ink-Layout: When changing card/cell dimensions, always recalculate how much content fits. Account for borders (2 chars), padding, margins, and sibling elements when computing the +remaining space for dynamic text. + +- Ink-Overflow: Ink has no `overflow: hidden`. The only way to prevent overflow is to ensure content never exceeds the container size — truncate text, limit list items, or cap height. + +- Ink-FlexGrow: Avoid `flexGrow={1}` on text containers inside fixed-height cards — the text will try to fill available space but Ink won't clip it if it exceeds the boundary. + +- Ink-HeightBudget: When computing how many rows/items fit vertically, count EVERY line used by headers, footers, margins, borders, and scroll indicators. Under-reserving vertical space (e.g., `height - 8` when chrome actually uses 16 lines) causes Ink to squeeze out margins between items, making borders collapse. Always audit the actual line count. + +- Ink-TrailingMargin: Don't apply `marginBottom` to the last item in a list — it wastes a line and can push content out of the container. Use conditional margins or container `gap`. ## Never -Never: Edit ui/desktop/openapi.json manually -Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to. -Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent. -Never: Skip cargo fmt -Never: Merge without running clippy -Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms +- Never: Edit ui/desktop/openapi.json manually +- Cargo.toml: For human-authored dependency changes, use `cargo add` instead of manually editing dependency entries unless there is a specific reason not to. +- Cargo.toml: Automated dependency bump PRs are exempt; when manual edits are necessary, keep `Cargo.lock` consistent. +- Never: Skip cargo fmt +- Never: Merge without running clippy +- Never: Comment self-evident operations (`// Initialize`, `// Return result`), getters/setters, constructors, or standard Rust idioms ## Entry Points - CLI: crates/goose-cli/src/main.rs