Add agents.md for AI-assisted bug fix skills#1476
Open
Tharsanan1 wants to merge 5 commits intowso2:mainfrom
Open
Add agents.md for AI-assisted bug fix skills#1476Tharsanan1 wants to merge 5 commits intowso2:mainfrom
Tharsanan1 wants to merge 5 commits intowso2:mainfrom
Conversation
Contributor
WalkthroughAdded a new agent guide Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
agents.md (2)
15-46: Add language specifier to the architecture diagram code block.The fenced code block containing the ASCII architecture diagram should specify a language for proper rendering. Use
textorplainfor ASCII diagrams.📝 Proposed fix
-``` +```text ┌─────────────────────────────────────────────────────────────┐ │ Management Portal / Developer Portal (React) │🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@agents.md` around lines 15 - 46, Update the fenced ASCII architecture diagram in agents.md so the opening code fence includes a language specifier (e.g., change the leading ``` to ```text or ```plain) so the diagram (the ASCII architecture diagram enclosed by triple backticks) renders as plain text; ensure only the opening fence is modified and the closing ``` remains unchanged.
327-329: Add language specifier to the commit message format code block.The fenced code block showing commit message format should specify a language (e.g.,
text) for proper rendering and AI parsing.📝 Proposed fix
-``` +```text <type>(<scope>): <subject></details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@agents.mdaround lines 327 - 329, The fenced code block showing the commit
message format (<type>(<scope>): <subject>) should include a language
specifier for proper rendering and AI parsing; update the block delimiter from
totext so the snippet reads as a text code block and ensure the content
remains exactly<type>(<scope>): <subject>.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@agents.md:
- Around line 50-72: The "Gateway Policies" table entry incorrectly references a
non-existent pathgateway/policies/; update the Module row for "Gateway
Policies" to point to the actual location
gateway/gateway-controller/default-policies/(replace the Path cell content),
and ensure any descriptive text still mentions built-in policy definitions (JWT
auth, API key, rate limiting, CORS, etc.) while removing or correcting the old
gateway/policies/reference in the table.- Around line 97-115: Update the Feature Inventory table entries for "Gateway
Management", "Gateway WebSocket Events", and "JWT Authentication Policy" to use
the correct documentation paths: change the Gateway Management path from
platform-api/spec/impls/gateway-management.md to
platform-api/spec/impls/gateway-management/gateway-management.md, change Gateway
WebSocket Events from platform-api/spec/impls/gateway-websocket-events.md to
platform-api/spec/impls/gateway-websocket-events/gateway-websocket-events.md,
and change JWT Authentication Policy from gateway/policies/ to
docs/gateway/policies/ so agents can locate the docs.
Nitpick comments:
In@agents.md:
- Around line 15-46: Update the fenced ASCII architecture diagram in agents.md
so the opening code fence includes a language specifier (e.g., change the
leadingtotext orplain) so the diagram (the ASCII architecture diagram enclosed by triple backticks) renders as plain text; ensure only the opening fence is modified and the closingremains unchanged.- Around line 327-329: The fenced code block showing the commit message format
(<type>(<scope>): <subject>) should include a language specifier for proper
rendering and AI parsing; update the block delimiter fromtotext so the
snippet reads as a text code block and ensure the content remains exactly
<type>(<scope>): <subject>.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `1d1d732c-832d-402d-a157-07018fb68ee7` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 4bc64854ed7ca59a42f48da80b7488c6b49ea4ab and cd1cd97cde85010f727d8716251270f1b9c5f506. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `agents.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comprehensive agent guide covering project structure, build/run commands, testing, architecture, configuration, and code patterns. AGENTS.md is a symlink to CLAUDE.md to support multiple AI tools. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Tharsanan1
force-pushed
the
add-agents-md
branch
from
02308fb to
097811d
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
CLAUDE.md (1)
192-193: Avoid uncertain wording in dependency tables.Line 192 uses
cobra (likely). For agent-facing docs, replace with a confirmed dependency (orTBDwith a follow-up issue) to avoid ambiguous automation behavior.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 192 - 193, Replace the ambiguous table cell text "cobra (likely)" with a confirmed dependency name or a clear placeholder like "TBD" and add a follow-up issue reference; specifically edit the table row that currently reads "| CLI | cobra (likely) | CLI framework |", changing "cobra (likely)" to either the verified CLI framework (e.g., "cobra") if confirmed or "TBD" plus note to open an issue, so automation and agent-facing docs no longer contain uncertain wording.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 13-51: The repository-tree fenced code block currently uses triple
backticks with no language tag; to satisfy markdownlint MD040, update the
opening fence (the triple-backtick line that precedes the tree diagram) to
include a language identifier such as "text" or "bash" (e.g., change "```" to
"```text"), leaving the tree content and closing fence unchanged so the block
renders the same while providing a language tag.
- Around line 55-70: The fenced architecture diagram block in CLAUDE.md is
missing a language tag which triggers markdownlint MD040; update the opening
triple-backtick that precedes the ASCII diagram (the fenced block containing
"Gateway-Controller (Go, Gin)" / "Router (Envoy)" etc.) to include a language
tag such as text (e.g., change ``` to ```text) so the code fence is labeled and
the lint warning is resolved.
---
Nitpick comments:
In `@CLAUDE.md`:
- Around line 192-193: Replace the ambiguous table cell text "cobra (likely)"
with a confirmed dependency name or a clear placeholder like "TBD" and add a
follow-up issue reference; specifically edit the table row that currently reads
"| CLI | cobra (likely) | CLI framework |", changing "cobra (likely)" to either
the verified CLI framework (e.g., "cobra") if confirmed or "TBD" plus note to
open an issue, so automation and agent-facing docs no longer contain uncertain
wording.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 83af9ed4-09a7-420b-8d6e-3bfa700c8d4a
📒 Files selected for processing (2)
AGENTS.mdCLAUDE.md
✅ Files skipped from review due to trivial changes (1)
- AGENTS.md
Add authentication details, key API endpoints, content type support, example LLM provider deployment, and stale database troubleshooting. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
AI agents can explore the directory structure themselves; keeping it in the guide adds maintenance burden without much value. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Remove Go workspace modules, version files, key technologies table, linting, CI/CD, and ports summary. These go stale quickly and agents can find them by reading go.work, go.mod, .golangci.yml, and .github/workflows/ directly. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
CLAUDE.md (1)
13-28:⚠️ Potential issue | 🟡 MinorAdd a language tag to the architecture diagram fence.
Line 13 uses an unlabeled fenced block. Please switch it to
```textto satisfy markdownlint MD040.Proposed fix
-``` +```text ┌──────────────────────────────────┐ │ Gateway-Controller (Go, Gin) │ ... -``` +```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 13 - 28, The fenced ASCII architecture diagram uses an unlabeled block; update the opening fence from ``` to ```text to satisfy markdownlint MD040. Locate the diagram fence in the CLAUDE.md content (the block beginning with the ASCII diagram and the triple backticks) and change only the opening fence to include the language tag `text`, leaving the closing ``` unchanged so the diagram renders the same but passes linting.
🧹 Nitpick comments (1)
CLAUDE.md (1)
243-245: Avoid hardcoded basic credentials in examples.Using
admin:admininline is convenient for dev, but it encourages unsafe copy/paste and repeatedly triggers leak scanners. Prefer placeholders or an environment variable example.Proposed refactor
-# Default dev credentials -curl -u admin:admin http://localhost:9090/llm-providers +# Dev credentials (example only) +curl -u "${APIP_GW_USER}:${APIP_GW_PASS}" http://localhost:9090/llm-providers ... -curl -u admin:admin -X POST http://localhost:9090/llm-providers \ +curl -u "${APIP_GW_USER}:${APIP_GW_PASS}" -X POST http://localhost:9090/llm-providers \Also applies to: 277-278
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 243 - 245, Replace the hardcoded credentials in the curl example ("curl -u admin:admin http://localhost:9090/llm-providers") with a safe placeholder or environment-variable pattern (e.g., use {USERNAME}:{PASSWORD} or refer to $DEV_AUTH) and update the duplicate example at lines 277-278 the same way; ensure the surrounding text briefly explains how to set the env var or substitute the placeholder before running the command.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 236-237: Update the documentation to use the actual route path:
replace instances of the string "/rest-apis" with "/apis" (e.g., in the sentence
describing registered routes and the example route listing) so the docs match
the generated handlers that register API resources at "/apis"; apply the same
replacement at the other mentioned occurrence.
- Around line 247-248: Documentation incorrectly states that a /health endpoint
does not exist; update the CLAUDE.md text around the current statement to
reflect that the gateway registers a GET /health route (see the gateway route
registration/GET /health), and clarify the observed behavior (unauthenticated
request returns {"error":"no valid authentication credentials provided"} rather
than a 404). Modify the sentence to state that GET /health is present and will
respond with an authentication error when credentials are missing, so agent
workflows and troubleshooting are not misled.
- Around line 251-268: The fenced code block containing the endpoint list (the
block starting with "GET /llm-providers ... POST /rest-apis
# Create REST API") is missing a language tag; update that fence to include a
language identifier (e.g., change ``` to ```text) to satisfy markdownlint MD040
and close the fence normally, ensuring the opening triple backticks are followed
by the language token and the closing triple backticks remain unchanged.
---
Duplicate comments:
In `@CLAUDE.md`:
- Around line 13-28: The fenced ASCII architecture diagram uses an unlabeled
block; update the opening fence from ``` to ```text to satisfy markdownlint
MD040. Locate the diagram fence in the CLAUDE.md content (the block beginning
with the ASCII diagram and the triple backticks) and change only the opening
fence to include the language tag `text`, leaving the closing ``` unchanged so
the diagram renders the same but passes linting.
---
Nitpick comments:
In `@CLAUDE.md`:
- Around line 243-245: Replace the hardcoded credentials in the curl example
("curl -u admin:admin http://localhost:9090/llm-providers") with a safe
placeholder or environment-variable pattern (e.g., use {USERNAME}:{PASSWORD} or
refer to $DEV_AUTH) and update the duplicate example at lines 277-278 the same
way; ensure the surrounding text briefly explains how to set the env var or
substitute the placeholder before running the command.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+236
to
+237
| The gateway controller REST API is served on port **9090** with **no base path prefix** — routes are registered at the root (e.g., `/llm-providers`, `/rest-apis`, not `/api/v1/...`). | ||
|
|
Contributor
There was a problem hiding this comment.
Use /apis instead of /rest-apis in docs.
The generated handlers register API resources at /apis; /rest-apis is inconsistent with actual routes.
Proposed fix
-The gateway controller REST API is served on port **9090** with **no base path prefix** — routes are registered at the root (e.g., `/llm-providers`, `/rest-apis`, not `/api/v1/...`).
+The gateway controller REST API is served on port **9090** with **no base path prefix** — routes are registered at the root (e.g., `/llm-providers`, `/apis`, not `/api/v1/...`).
...
-GET /rest-apis # List REST APIs
-POST /rest-apis # Create REST API
+GET /apis # List APIs
+POST /apis # Create APIAlso applies to: 266-268
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 236 - 237, Update the documentation to use the actual
route path: replace instances of the string "/rest-apis" with "/apis" (e.g., in
the sentence describing registered routes and the example route listing) so the
docs match the generated handlers that register API resources at "/apis"; apply
the same replacement at the other mentioned occurrence.
Comment on lines
+247
to
+248
| There is no `/health` endpoint on the management API. A request without credentials returning `{"error":"no valid authentication credentials provided"}` confirms the server is running. | ||
|
|
Contributor
There was a problem hiding this comment.
Correct the /health endpoint statement.
Line 247 says /health does not exist, but gateway route registration includes GET /health. This will mislead agent workflows and troubleshooting steps.
Proposed fix
-There is no `/health` endpoint on the management API. A request without credentials returning `{"error":"no valid authentication credentials provided"}` confirms the server is running.
+`/health` is available on the management API (`GET /health`). In dev mode, protected endpoints without credentials should return an authentication error, which also confirms the server is running.📝 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.
Suggested change
| There is no `/health` endpoint on the management API. A request without credentials returning `{"error":"no valid authentication credentials provided"}` confirms the server is running. | |
| `/health` is available on the management API (`GET /health`). In dev mode, protected endpoints without credentials should return an authentication error, which also confirms the server is running. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 247 - 248, Documentation incorrectly states that a
/health endpoint does not exist; update the CLAUDE.md text around the current
statement to reflect that the gateway registers a GET /health route (see the
gateway route registration/GET /health), and clarify the observed behavior
(unauthenticated request returns {"error":"no valid authentication credentials
provided"} rather than a 404). Modify the sentence to state that GET /health is
present and will respond with an authentication error when credentials are
missing, so agent workflows and troubleshooting are not misled.
Comment on lines
+251
to
+268
| ``` | ||
| GET /llm-providers # List LLM providers | ||
| POST /llm-providers # Create LLM provider | ||
| GET /llm-providers/:id # Get LLM provider by handle | ||
| PUT /llm-providers/:id # Update LLM provider | ||
| DELETE /llm-providers/:id # Delete LLM provider | ||
|
|
||
| GET /llm-proxies # List LLM proxies | ||
| POST /llm-proxies # Create LLM proxy | ||
| GET /llm-proxies/:id # Get LLM proxy by handle | ||
| PUT /llm-proxies/:id # Update LLM proxy | ||
| DELETE /llm-proxies/:id # Delete LLM proxy | ||
|
|
||
| GET /llm-provider-templates # List provider templates | ||
| POST /llm-provider-templates # Create template | ||
| GET /rest-apis # List REST APIs | ||
| POST /rest-apis # Create REST API | ||
| ``` |
Contributor
There was a problem hiding this comment.
Label the endpoint list fenced block.
Line 251 also has an unlabeled fence. Add a language tag (e.g., text) for markdownlint MD040 compliance.
Proposed fix
-```
+```text
GET /llm-providers # List LLM providers
...
POST /rest-apis # Create REST API
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 251-251: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 251 - 268, The fenced code block containing the
endpoint list (the block starting with "GET /llm-providers ... POST
/rest-apis # Create REST API") is missing a language tag;
update that fence to include a language identifier (e.g., change ``` to ```text)
to satisfy markdownlint MD040 and close the fence normally, ensuring the opening
triple backticks are followed by the language token and the closing triple
backticks remain unchanged.
Document IT_FEATURE_PATHS env var and Godog tag filtering for running individual .feature files. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
CLAUDE.md (3)
191-191:⚠️ Potential issue | 🟠 MajorCorrect the
/healthendpoint statement.Line 191 says
/healthdoes not exist, but gateway routes includeGET /health. This should be updated to avoid broken troubleshooting guidance.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 191, Update the incorrect claim that a /health endpoint does not exist: change the sentence referencing the management API to state that the gateway exposes GET /health and that an unauthenticated request will return {"error":"no valid authentication credentials provided"} (confirming the server is running) instead of saying the endpoint is absent; edit the text around the existing `/health` mention to reflect the correct route name (GET /health) and its unauthenticated response.
180-181:⚠️ Potential issue | 🟠 MajorUse
/apisinstead of/rest-apisin route documentation.The documented path is inconsistent with the generated handlers and will mislead agent workflows. Replace
/rest-apiswith/apisin both the overview and endpoint list.Also applies to: 210-211
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 180 - 181, Update the route documentation by replacing the incorrect path string "/rest-apis" with "/apis" wherever it appears in the CLAUDE.md overview and endpoint list (including the other occurrences noted around lines 210-211); ensure both the high-level description that mentions routes at root and each endpoint example use "/apis" (e.g., change "/rest-apis" → "/apis") so the docs match the generated handlers.
13-13:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks.
Both fences are unlabeled; add
text(or another suitable language) to satisfy MD040 and keep docs lint-clean.Also applies to: 195-195
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 13, The two unlabeled fenced code blocks in CLAUDE.md should be given a language identifier (e.g., change ``` to ```text) to satisfy MD040; locate the unlabeled triple-backtick fences and add "text" (or another appropriate language) after the opening backticks so both code blocks are labeled.
🧹 Nitpick comments (1)
CLAUDE.md (1)
186-189: Avoid embedding credentials directly in curl examples.Even for dev docs,
-u admin:admintends to be copy-pasted. Prefer env vars/placeholders and add an explicit “dev-only default credentials” warning.Suggested doc tweak
-# Default dev credentials -curl -u admin:admin http://localhost:9090/llm-providers +# Dev-only default credentials (do not use outside local development) +export APIP_DEV_USER=admin +export APIP_DEV_PASS=admin +curl -u "${APIP_DEV_USER}:${APIP_DEV_PASS}" http://localhost:9090/llm-providers ... -curl -u admin:admin -X POST http://localhost:9090/llm-providers \ +curl -u "${APIP_DEV_USER}:${APIP_DEV_PASS}" -X POST http://localhost:9090/llm-providers \Also applies to: 220-223
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 186 - 189, Replace the embedded credentials in the curl examples (the `-u admin:admin` snippet) with either environment-variable placeholders (e.g. `-u "$DEV_USER:$DEV_PASS"`) or clear template placeholders (e.g. `-u '{{USERNAME}}:{{PASSWORD}}'`) and add an explicit one-line warning immediately above the example stating these are dev-only default credentials (admin/admin) and must not be used in production; apply this change to the shown curl example and the other occurrence later in the file.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CLAUDE.md`:
- Line 191: Update the incorrect claim that a /health endpoint does not exist:
change the sentence referencing the management API to state that the gateway
exposes GET /health and that an unauthenticated request will return {"error":"no
valid authentication credentials provided"} (confirming the server is running)
instead of saying the endpoint is absent; edit the text around the existing
`/health` mention to reflect the correct route name (GET /health) and its
unauthenticated response.
- Around line 180-181: Update the route documentation by replacing the incorrect
path string "/rest-apis" with "/apis" wherever it appears in the CLAUDE.md
overview and endpoint list (including the other occurrences noted around lines
210-211); ensure both the high-level description that mentions routes at root
and each endpoint example use "/apis" (e.g., change "/rest-apis" → "/apis") so
the docs match the generated handlers.
- Line 13: The two unlabeled fenced code blocks in CLAUDE.md should be given a
language identifier (e.g., change ``` to ```text) to satisfy MD040; locate the
unlabeled triple-backtick fences and add "text" (or another appropriate
language) after the opening backticks so both code blocks are labeled.
---
Nitpick comments:
In `@CLAUDE.md`:
- Around line 186-189: Replace the embedded credentials in the curl examples
(the `-u admin:admin` snippet) with either environment-variable placeholders
(e.g. `-u "$DEV_USER:$DEV_PASS"`) or clear template placeholders (e.g. `-u
'{{USERNAME}}:{{PASSWORD}}'`) and add an explicit one-line warning immediately
above the example stating these are dev-only default credentials (admin/admin)
and must not be used in production; apply this change to the shown curl example
and the other occurrence later in the file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agents.mdat repo root — product context file for AI-assisted bug fix skills (/reproduce,/plan-fix,/implement, etc.)agents.mdfor policy integration testingTest plan
/reproduceagainst a sample issue and confirm it reads context correctly🤖 Generated with Claude Code
Summary by CodeRabbit