docs: add CLAUDE.md for AI agent guidance#489
Conversation
Captures build commands, architecture, versioning model (directory layout, hugo.yaml registration, RELEASE_TAG derivation, new-version bootstrap), autogenerated-file conventions, and the upstream-triggered docs update flow (cozystack/cozystack#2214). Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
myasnikovdaniil
requested review from
lexfrei
and removed request for
kvaps and
lllamnyp
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughA new Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a CLAUDE.md file to provide comprehensive guidance for AI agents working within the repository, covering project architecture, build commands, and versioning workflows. The review feedback suggests improving consistency by using Makefile targets for OpenAPI downloads and correcting the documentation regarding the init-version command, as the Makefile wrapper does not support the --from flag mentioned in the initial draft.
| make serve | ||
|
|
||
| # Production build | ||
| ./hack/download_openapi.sh && hugo --gc --minify |
There was a problem hiding this comment.
For consistency with the other commands listed in this section and to leverage the existing build workflow, it is recommended to use the Makefile target download-openapi-all instead of calling the script directly.
| ./hack/download_openapi.sh && hugo --gc --minify | |
| make download-openapi-all && hugo --gc --minify |
| - No `RELEASE_TAG` → defaults to `DOC_VERSION=v1.2`, `BRANCH=main` (uses current upstream `main`, non-reproducible) | ||
|
|
||
| **Creating a new version (e.g., `v1.3`)** | ||
| 1. `make init-version DOC_VERSION=v1.3` — `hack/init_version.sh` copies from the auto-detected latest existing version (or `--from vX.Y`), strips `api.json` (downloaded at build time), and rewrites internal `/docs/<old>/` and `"docs/<old>/` refs to the new version |
There was a problem hiding this comment.
The make init-version target in the Makefile (line 66) only passes the --version flag to the underlying script. It does not support the --from flag. To use a specific source version, the script hack/init_version.sh must be called directly. Clarifying this will prevent the AI agent from attempting to pass unsupported arguments to make.
| 1. `make init-version DOC_VERSION=v1.3` — `hack/init_version.sh` copies from the auto-detected latest existing version (or `--from vX.Y`), strips `api.json` (downloaded at build time), and rewrites internal `/docs/<old>/` and `"docs/<old>/` refs to the new version | |
| 1. make init-version DOC_VERSION=v1.3 — copies from the auto-detected latest existing version (or use hack/init_version.sh --version v1.3 --from vX.Y for a specific source), strips api.json (downloaded at build time), and rewrites internal /docs/<old>/ and "docs/<old>/ refs to the new version |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
CLAUDE.md (1)
108-108: Minor wording nit: capitalize “Markdown”.Consider changing “markdown” → “Markdown” for proper noun consistency in docs text.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 108, Update the wording in CLAUDE.md by capitalizing the word "Markdown" where it appears in the sentence "Goldmark rendering has `unsafe: true` enabled (raw HTML allowed in markdown)"; change "markdown" to "Markdown" to maintain proper noun consistency.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@CLAUDE.md`:
- Line 108: Update the wording in CLAUDE.md by capitalizing the word "Markdown"
where it appears in the sentence "Goldmark rendering has `unsafe: true` enabled
(raw HTML allowed in markdown)"; change "markdown" to "Markdown" to maintain
proper noun consistency.
2 participants
Summary
CLAUDE.mdguidance file for AI coding agents so they can contribute without re-deriving repo conventions each session.Contents
make serve, production build,update-*/template-*targets, version bootstrap)v0,vX.Y),hugo.yamlregistration (latest_version_id+versions[]), where to add changes, autogenerated-file conventions,RELEASE_TAGderivation rules, new-version bootstrap flow, per-version OpenAPI handlingcozystack/cozystacktags.yamlupdate-website-docsjob ([docs] Added openapi and go types codegeneration for apps cozystack#2214); the old website-side daily cron is flagged obsoleteTest plan
Summary by CodeRabbit