docs: optimize AI agent instructions for token efficiency #471
Conversation
- Reduce copilot-instructions.md to thin pointer file (~500 tokens) - Add AGENTS.md with operational procedures (on-demand loading) - Implement tiered loading to minimize auto-loaded token cost - Add token efficiency headers explaining load strategy Instructions now use thin pointer architecture: essential context auto-loads, detailed procedures load on-demand via #file reference.
WalkthroughThis PR updates and adds documentation files to provide comprehensive Copilot instructions and operational guidance. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10-15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
|
Coverage summary from CodacySee diff coverage on Codacy
Coverage variation details
Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: Diff coverage details
Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: See your quality gate settings Change summary preferences |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #471 +/- ##
=======================================
Coverage 89.65% 89.65%
=======================================
Files 3 3
Lines 116 116
=======================================
Hits 104 104
Misses 12 12
🚀 New features to boost your workflow:
|
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In @.github/copilot-instructions.md:
- Around line 34-35: The documentation has inconsistent cache TTLs: one place
shows "10min/1hr TTL" while another shows "600s"; pick the correct TTL value
(e.g., 600s or 10min/1hr) and update all occurrences so they match—specifically
replace the "10min/1hr TTL" text and any later mention of "600s" (and the
related paragraph at the other noted occurrence) with the agreed-upon TTL string
so the architecture section and cache note are consistent.
- Around line 78-81: The two stray list items ("5. **Caching**: In-memory cache
(10 min TTL) with `X-Cache` headers (HIT/MISS)" and "6. **Async/Await**: All
database operations are async") should be removed from their current orphan
position or moved into the appropriate section (e.g., the "Core Conventions" or
"Architecture" list); update the destination list so numbering/bullets are
consistent and delete the original lines so no disconnected items remain. Ensure
the moved items keep their Markdown formatting and update any surrounding lists
or headings to preserve document structure.
- Around line 57-68: Update the port in the quick commands snippet so it matches
the rest of the docs: change the uvicorn command string "uvicorn main:app
--reload --host 0.0.0.0 --port 8000" to use --port 9000 and update the Swagger
URL "http://localhost:8000/docs" to "http://localhost:9000/docs"; ensure any
other occurrences of "8000" in that snippet are replaced with "9000" for
consistency.
In `@AGENTS.md`:
- Around line 229-230: Replace the bare URL in the prose ("Open
http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons")
by wrapping it in angle brackets or inline code formatting to satisfy MD034;
e.g., change the phrase to use `<http://localhost:9000/docs>` or backticks
around the URL so the line reads like "Open <http://localhost:9000/docs> -
Interactive Swagger UI with 'Try it out' buttons" or similar.
- Around line 162-163: The fenced code block containing the architecture snippet
that starts with "routes/ # FastAPI endpoints with caching" is missing
a language tag (MD040); add a language identifier such as text (e.g., change the
opening fence to ```text) so the block becomes a labeled fenced code block and
satisfies markdownlint; locate the block in AGENTS.md and update the opening
fence accordingly.
| - **Cache**: aiocache SimpleMemoryCache (10min/1hr TTL) | ||
|
|
There was a problem hiding this comment.
Cache TTL inconsistency.
“10min/1hr TTL” in the architecture section conflicts with the later cache note (600s). Please verify and make these consistent.
Also applies to: 176-179
🤖 Prompt for AI Agents
In @.github/copilot-instructions.md around lines 34 - 35, The documentation has
inconsistent cache TTLs: one place shows "10min/1hr TTL" while another shows
"600s"; pick the correct TTL value (e.g., 600s or 10min/1hr) and update all
occurrences so they match—specifically replace the "10min/1hr TTL" text and any
later mention of "600s" (and the related paragraph at the other noted
occurrence) with the agreed-upon TTL string so the architecture section and
cache note are consistent.
| ```bash | ||
| # Run with hot reload | ||
| uvicorn main:app --reload --host 0.0.0.0 --port 8000 | ||
|
|
||
| # Test with coverage | ||
| pytest --cov=. --cov-report=term-missing | ||
|
|
||
| # Docker | ||
| docker compose up | ||
|
|
||
| # Swagger: http://localhost:8000/docs | ||
| ``` |
There was a problem hiding this comment.
Port mismatch with the rest of the docs.
Quick Commands uses port 8000 while the rest of the instructions and AGENTS.md use 9000. Align the port to avoid confusion.
💡 Suggested tweak
-uvicorn main:app --reload --host 0.0.0.0 --port 8000
+uvicorn main:app --reload --host 0.0.0.0 --port 9000
-# Swagger: http://localhost:8000/docs
+# Swagger: http://localhost:9000/docs📝 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.
| ```bash | |
| # Run with hot reload | |
| uvicorn main:app --reload --host 0.0.0.0 --port 8000 | |
| # Test with coverage | |
| pytest --cov=. --cov-report=term-missing | |
| # Docker | |
| docker compose up | |
| # Swagger: http://localhost:8000/docs | |
| ``` | |
| # Run with hot reload | |
| uvicorn main:app --reload --host 0.0.0.0 --port 9000 | |
| # Test with coverage | |
| pytest --cov=. --cov-report=term-missing | |
| # Docker | |
| docker compose up | |
| # Swagger: http://localhost:9000/docs |
🤖 Prompt for AI Agents
In @.github/copilot-instructions.md around lines 57 - 68, Update the port in the
quick commands snippet so it matches the rest of the docs: change the uvicorn
command string "uvicorn main:app --reload --host 0.0.0.0 --port 8000" to use
--port 9000 and update the Swagger URL "http://localhost:8000/docs" to
"http://localhost:9000/docs"; ensure any other occurrences of "8000" in that
snippet are replaced with "9000" for consistency.
| 💡 **Why this structure?** Copilot auto-loads this file on every chat (~500 tokens). Loading `AGENTS.md` or `SKILLS/` explicitly gives you deep context only when needed, saving 80% of your token budget! | ||
| 5. **Caching**: In-memory cache (10 min TTL) with `X-Cache` headers (HIT/MISS) | ||
| 6. **Async/Await**: All database operations are async | ||
|
|
There was a problem hiding this comment.
Stray list items break structure.
Lines 79–81 look like leftover list entries and appear outside any section, which is confusing. Either remove them or move into the appropriate “Core Conventions” or “Architecture” list.
🤖 Prompt for AI Agents
In @.github/copilot-instructions.md around lines 78 - 81, The two stray list
items ("5. **Caching**: In-memory cache (10 min TTL) with `X-Cache` headers
(HIT/MISS)" and "6. **Async/Await**: All database operations are async") should
be removed from their current orphan position or moved into the appropriate
section (e.g., the "Core Conventions" or "Architecture" list); update the
destination list so numbering/bullets are consistent and delete the original
lines so no disconnected items remain. Ensure the moved items keep their
Markdown formatting and update any surrounding lists or headings to preserve
document structure.
| ``` | ||
| routes/ # FastAPI endpoints with caching |
There was a problem hiding this comment.
Add a language tag to the fenced block.
Markdownlint flags the architecture diagram block as missing a language. Use text (or md) to satisfy MD040.
💡 Suggested tweak
-```
+```text
Route → Service → Database
↓ ↓
Cache Session</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.18.1)
162-162: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 162 - 163, The fenced code block containing the
architecture snippet that starts with "routes/ # FastAPI endpoints with
caching" is missing a language tag (MD040); add a language identifier such as
text (e.g., change the opening fence to ```text) so the block becomes a labeled
fenced code block and satisfies markdownlint; locate the block in AGENTS.md and
update the opening fence accordingly.
| Open http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons | ||
|
|
There was a problem hiding this comment.
Avoid bare URL in prose.
Wrap the URL in angle brackets or code formatting to satisfy MD034 and keep rendering consistent.
💡 Suggested tweak
-Open http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons
+Open <http://localhost:9000/docs> - Interactive Swagger UI with "Try it out" buttons📝 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.
| Open http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons | |
| Open <http://localhost:9000/docs> - Interactive Swagger UI with "Try it out" buttons |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
229-229: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 229 - 230, Replace the bare URL in the prose ("Open
http://localhost:9000/docs - Interactive Swagger UI with "Try it out" buttons")
by wrapping it in angle brackets or inline code formatting to satisfy MD034;
e.g., change the phrase to use `<http://localhost:9000/docs>` or backticks
around the URL so the line reads like "Open <http://localhost:9000/docs> -
Interactive Swagger UI with 'Try it out' buttons" or similar.
Instructions now use thin pointer architecture: essential context auto-loads, detailed procedures load on-demand via #file reference.
This change is
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.