docs: rewrite AGENTS.md for clarity and density#821
Conversation
WalkthroughThis PR updates the repository's contributor documentation by restructuring the main ChangesContributor Workflow Documentation
🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Restructure AGENTS.md with progressive disclosure: keep high-frequency instructions inline, move reference material to docs/. - Add architecture section with directory layout - Add prerequisites and local run command - Fix stale UI path (ui/ -> ui-svelte/) - Consolidate testing commands into compact list - Extract commit format rules into docs/commit-format.md - Extract code review guidelines into docs/code-review.md - Add contributing guidance to maintain the pattern
jeremyeder
force-pushed
the
worktree-improve-claude-md
branch
from
16f065e to
2bc0d7c
Compare
|
@coderabbitai review this is a small change but it has a larger impact as things expand. |
🧩 Analysis chain🏁 Script executed: #!/bin/bash
echo "=== AGENTS.md ==="
cat AGENTS.md
echo ""
echo "=== docs/commit-format.md ==="
cat docs/commit-format.md 2>/dev/null || echo "FILE NOT FOUND"
echo ""
echo "=== docs/code-review.md ==="
cat docs/code-review.md 2>/dev/null || echo "FILE NOT FOUND"
echo ""
echo "=== docs/ directory listing ==="
ls -la docs/ 2>/dev/null || echo "docs/ directory not found"
echo ""
echo "=== ui directory check ==="
ls -d ui 2>/dev/null && echo "ui/ EXISTS" || echo "ui/ NOT FOUND"
ls -d ui-svelte 2>/dev/null && echo "ui-svelte/ EXISTS" || echo "ui-svelte/ NOT FOUND"Length of output: 4236
M1 — Missing trigger hints for the
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/commit-format.md (1)
15-20: ⚡ Quick winAdd explicit scope-prefix guidance for commit subjects.
The example uses
proxy:but the rules don’t define how to choose allowed prefixes, which can cause inconsistent commit subjects. Add a short rule listing accepted scopes (for example:proxy,internal,ui,docs,cmd,config) and when to use each.Suggested patch
## Rules for Pull Requests - Keep them short and focused on changes - Never include a test plan - Write the summary using the same style rules as commit messages +- Use a scope prefix that matches the primary area changed (e.g., `proxy:`, `internal:`, `ui:`, `docs:`, `cmd:`, `config:`)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/commit-format.md` around lines 15 - 20, Add an explicit rule in the commit/PR section that lists allowed commit subject scopes and short guidance for choosing them (e.g., allowed scopes: proxy, internal, ui, docs, cmd, config), require lowercase single-word scopes followed by a colon (example: "proxy: fix request routing"), and map each scope to when to use it (proxy = networking/proxy code, internal = non-public library changes, ui = frontend/UX, docs = documentation-only, cmd = CLI/commands, config = build/config changes); update the existing example that uses "proxy:" to include a couple more example subjects demonstrating the format and choice of scope.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Line 48: Add explicit trigger cues in AGENTS.md next to each linked doc
(docs/commit-format.md and docs/code-review.md) that state the precise
conditions when the agent should load them — e.g., "Load docs/commit-format.md
when composing or validating commit messages or PR descriptions" and "Load
docs/code-review.md when performing or summarizing code reviews or evaluating PR
diffs." Update the AGENTS.md link lines to include these short, actionable
triggers so the agent only fetches each document under the specified contexts to
save tokens and avoid ambiguous behavior.
- Line 12: The fenced code block in AGENTS.md (the directory map block that
starts with ``` and lists files like "llama-swap.go" and "config-schema.json")
lacks a language specifier; update that opening fence to ```text so the block
becomes a ```text fenced code block to satisfy markdownlint MD040 and keep
formatting explicit.
In `@docs/code-review.md`:
- Around line 5-9: The guidance line "Limit your code review to three items with
the highest priority first" incorrectly caps High-severity findings; update the
documentation text so High items are reported without the three-item cap while
keeping the "top three" limit only for Medium and Low findings — edit the
sentence that currently reads "Limit your code review to three items with the
highest priority first" (and any related bullets) to explicitly exempt
High-severity issues and clarify the ordering rules.
In `@docs/commit-format.md`:
- Line 3: The fenced code block starting with ``` and containing the example
commit message (lines showing "proxy: add new feature" and "fixes `#123`") lacks a
language tag; update the opening fence to include a language such as text (e.g.
change ``` to ```text) so markdownlint rule MD040 passes and the snippet renders
consistently.
---
Nitpick comments:
In `@docs/commit-format.md`:
- Around line 15-20: Add an explicit rule in the commit/PR section that lists
allowed commit subject scopes and short guidance for choosing them (e.g.,
allowed scopes: proxy, internal, ui, docs, cmd, config), require lowercase
single-word scopes followed by a colon (example: "proxy: fix request routing"),
and map each scope to when to use it (proxy = networking/proxy code, internal =
non-public library changes, ui = frontend/UX, docs = documentation-only, cmd =
CLI/commands, config = build/config changes); update the existing example that
uses "proxy:" to include a couple more example subjects demonstrating the format
and choice of scope.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 4882dd96-dd52-4d34-8c0f-dc95f77ad17b
📒 Files selected for processing (3)
AGENTS.mddocs/code-review.mddocs/commit-format.md
| - keep them short and focused on changes. | ||
| - never include a test plan | ||
| - write the summary using the same style rules as commit message | ||
| ``` |
There was a problem hiding this comment.
Specify a language for the architecture fenced block (MD040).
Use text for the directory map fence to satisfy markdownlint and keep formatting explicit.
Suggested patch
-```
+```text
llama-swap.go # entry point, flag parsing, server startup
@@
config-schema.json # JSON schema for config validation</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 12-12: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` at line 12, The fenced code block in AGENTS.md (the directory map
block that starts with ``` and lists files like "llama-swap.go" and
"config-schema.json") lacks a language specifier; update that opening fence to
```text so the block becomes a ```text fenced code block to satisfy markdownlint
MD040 and keep formatting explicit.
Source: Linters/SAST tools
| - Just say "Done." when there is no further action | ||
| - Use the GitHub CLI `gh` to create pull requests and work with GitHub | ||
|
|
||
| See [docs/commit-format.md](docs/commit-format.md) and [docs/code-review.md](docs/code-review.md). |
There was a problem hiding this comment.
Add trigger cues for when to load each linked doc.
Linking both files is good, but explicit “when to read” cues are needed to preserve token savings and avoid ambiguous agent behavior.
Suggested patch
-See [docs/commit-format.md](docs/commit-format.md) and [docs/code-review.md](docs/code-review.md).
+- Before committing or writing a PR summary, read [docs/commit-format.md](docs/commit-format.md).
+- Before performing a code review, read [docs/code-review.md](docs/code-review.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` at line 48, Add explicit trigger cues in AGENTS.md next to each
linked doc (docs/commit-format.md and docs/code-review.md) that state the
precise conditions when the agent should load them — e.g., "Load
docs/commit-format.md when composing or validating commit messages or PR
descriptions" and "Load docs/code-review.md when performing or summarizing code
reviews or evaluating PR diffs." Update the AGENTS.md link lines to include
these short, actionable triggers so the agent only fetches each document under
the specified contexts to save tokens and avoid ambiguous behavior.
| - High: must fix (security, race conditions, critical bugs) | ||
| - Medium: recommended improvements (coding style, missing functionality, inconsistencies) | ||
| - Low: nice to have changes and nits | ||
| - Include a suggestion with each discovered item | ||
| - Limit your code review to three items with the highest priority first |
There was a problem hiding this comment.
Do not cap High-severity findings at three.
The current limit can hide additional must-fix issues. Keep the “top three” cap for Medium/Low, but always report all High-severity items first.
Suggested patch
-- Limit your code review to three items with the highest priority first
+- Report all High-severity items. For Medium/Low items, limit to the top three by priority.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - High: must fix (security, race conditions, critical bugs) | |
| - Medium: recommended improvements (coding style, missing functionality, inconsistencies) | |
| - Low: nice to have changes and nits | |
| - Include a suggestion with each discovered item | |
| - Limit your code review to three items with the highest priority first | |
| - High: must fix (security, race conditions, critical bugs) | |
| - Medium: recommended improvements (coding style, missing functionality, inconsistencies) | |
| - Low: nice to have changes and nits | |
| - Include a suggestion with each discovered item | |
| - Report all High-severity items. For Medium/Low items, limit to the top three by priority. |
🧰 Tools
🪛 LanguageTool
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...ctionality, inconsistencies) - Low: nice to have changes and nits - Include a sugges...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/code-review.md` around lines 5 - 9, The guidance line "Limit your code
review to three items with the highest priority first" incorrectly caps
High-severity findings; update the documentation text so High items are reported
without the three-item cap while keeping the "top three" limit only for Medium
and Low findings — edit the sentence that currently reads "Limit your code
review to three items with the highest priority first" (and any related bullets)
to explicitly exempt High-severity issues and clarify the ordering rules.
| @@ -0,0 +1,19 @@ | |||
| # Commit Message Format | |||
|
|
|||
| ``` | |||
There was a problem hiding this comment.
Specify a language for the fenced code block (MD040).
Set the fence to text (or markdown) so markdownlint passes consistently.
Suggested patch
-```
+```text
proxy: add new feature
@@
fixes `#123`</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 3-3: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/commit-format.md` at line 3, The fenced code block starting with ``` and
containing the example commit message (lines showing "proxy: add new feature"
and "fixes `#123`") lacks a language tag; update the opening fence to include a
language such as text (e.g. change ``` to ```text) so markdownlint rule MD040
passes and the snippet renders consistently.
Source: Linters/SAST tools
1 participant
Restructure AGENTS.md to be more scannable and adopt a progressive disclosure approach: keep high-frequency instructions (architecture, testing, workflow) inline, and move reference material (commit format, code review guidelines) into dedicated files under
docs/.Changes:
ui/→ui-svelte/)docs/commit-format.mddocs/code-review.mddocs/from AGENTS.md so agents load details on demandProgressive disclosure:
AGENTS.md is loaded into every agent context window. By keeping it lean and linking to
docs/for less-frequently-needed reference material, agents get the essentials immediately and can read the detailed docs only when relevant (e.g., before committing or reviewing code). This reduces baseline token cost while preserving all the information.Context window impact:
The 32.6% word count reduction (340 → 229 words) also improves information density — more actionable content per token for the model to attend to.