refactor: make AGENTS.md source of truth, CLAUDE.md as symlink#42
refactor: make AGENTS.md source of truth, CLAUDE.md as symlink#42recoupableorg merged 3 commits intomainfrom
Conversation
📝 WalkthroughWalkthroughA new documentation file AGENTS.md is added to guide coding agents through repository workflows, project structure, development practices, configuration, branding conventions, MDX writing standards, API reference guidelines, and core code principles. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 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 |
| @@ -0,0 +1,110 @@ | |||
| # Agent Instructions | |||
|
|
|||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |||
There was a problem hiding this comment.
nit (optional) - more inclusive agent naming
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |
| This file provides guidance to coding agents like Claude Code (claude.ai/code) and OpenCode when working with code in this repository. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 27-43: The fenced code block containing the directory tree in
AGENTS.md is missing a language specifier; update the opening fence (the triple
backticks that start the directory tree) to include a language like "text"
(e.g., change ``` to ```text) so the tree renders correctly and satisfies
linting; locate the fenced block that begins with the directory listing (lines
showing "docs/" and the tree entries) and add the language specifier to the
opening fence.
- Line 50: Replace the outdated CLI invocation "npx mintlify@latest dev" in
AGENTS.md with the correct Mintlify CLI command for this repository: if the repo
uses docs.json projects use "npx mint dev", otherwise for mint.json projects use
"mintlify dev"; inspect the repo root to determine whether docs.json or
mint.json is present and update the single line containing "npx mintlify@latest
dev" accordingly.
| ``` | ||
| docs/ | ||
| ├── docs.json # Mintlify configuration (navigation, branding, theme) | ||
| ├── index.mdx # Homepage | ||
| ├── quickstart.mdx # Getting started guide | ||
| ├── development.mdx # Development setup guide | ||
| ├── api-reference/ # API endpoint documentation | ||
| │ ├── introduction.mdx | ||
| │ ├── openapi.json # OpenAPI spec for API endpoints | ||
| │ └── [category]/ # Grouped API endpoints (tasks, artists, chat, etc.) | ||
| ├── essentials/ # Core documentation pages | ||
| ├── ai-tools/ # AI tool integration guides | ||
| ├── logo/ # Brand logos (light.svg, dark.svg) | ||
| ├── favicon.svg # Site favicon | ||
| ├── images/ # Documentation images | ||
| └── snippets/ # Reusable MDX snippets | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The directory tree structure should specify a language for the code fence to improve rendering and satisfy linting rules.
📝 Proposed fix
-```
+```text
docs/
├── docs.json # Mintlify configuration (navigation, branding, theme)🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 27-27: 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 `@AGENTS.md` around lines 27 - 43, The fenced code block containing the
directory tree in AGENTS.md is missing a language specifier; update the opening
fence (the triple backticks that start the directory tree) to include a language
like "text" (e.g., change ``` to ```text) so the tree renders correctly and
satisfies linting; locate the fenced block that begins with the directory
listing (lines showing "docs/" and the tree entries) and add the language
specifier to the opening fence.
| Mintlify docs are deployed automatically. To preview locally: | ||
|
|
||
| ```bash | ||
| npx mintlify@latest dev |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Mintlify CLI dev command 2025 2026 documentation
💡 Result:
Mintlify has two “dev” commands in their docs, depending on which CLI/project format you’re using:
-
If your repo has
docs.json(older/common Mintlify docs format): install themintCLI and run:npm i -g mintmint dev(ornpx mint dev)
Local preview:http://localhost:3000and you can change the port with--port(e.g.,mint dev --port 3333). [1][2]
-
If your repo has
mint.json(Starter Kit / newer flow): install themintlifyCLI and run:npm i -g mintlifymintlify dev
Local preview:http://localhost:3000and you can change the port with--port(e.g.,mintlify dev --port 3333). [3]
Rule of thumb: check your repo root—docs.json ⇒ mint dev; mint.json ⇒ mintlify dev. [2][3]
Sources
[1] Mintlify “Install the CLI / Preview locally” (mint dev) https://www.mintlify.com/docs/installation
[2] Mintlify “CLI installation” (mint dev, npx mint dev, --port, updates) https://mintlify.com/docs/installation
[3] Mintlify Starter Kit “Development” (mintlify dev, mint.json) https://www.mintlify.app/development
Update Mintlify CLI command to match current documentation.
The command npx mintlify@latest dev does not align with official Mintlify CLI documentation. Use one of these commands instead:
- For
docs.jsonprojects:npx mint dev - For
mint.jsonprojects:mintlify dev
Check your repo root to determine which project format is being used, then apply the corresponding command.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 50, Replace the outdated CLI invocation "npx
mintlify@latest dev" in AGENTS.md with the correct Mintlify CLI command for this
repository: if the repo uses docs.json projects use "npx mint dev", otherwise
for mint.json projects use "mintlify dev"; inspect the repo root to determine
whether docs.json or mint.json is present and update the single line containing
"npx mintlify@latest dev" accordingly.
3 participants
Makes
AGENTS.mdthe source of truth for AI agent instructions.CLAUDE.mdis now a symlink to it.Summary by CodeRabbit