Add AI guide first pass#552
Conversation
boutell
left a comment
boutell
left a comment
There was a problem hiding this comment.
A good direction. Some notes.
Also I would state the obvious and say that you should first begin your project by using our CLI or git cloning one of our official starter kits because this gives you a structure that matches our documentation and that will be helpful to both you and the AI agent.
| ] | ||
| }, | ||
| { | ||
| text: "Using AI Effectively", |
There was a problem hiding this comment.
Where will the title tag come from? This is fine for the sidebar, indeed
|
|
||
| This can be a drawback. Any code the AI generates exists only in the chat, and you are responsible for copying it into the right files or applying a diff patch in your project, which adds friction and introduces room for error. However, this can also be desirable for teams that prefer to keep AI-generated code out of the codebase entirely. Chat interfaces are well-suited to answering architecture and implementation questions, helping you reason through the right solution before writing it yourself, or reviewing a focused set of files without letting an AI tool touch your project directly. | ||
|
|
||
| **In-project agentic tools** (Claude Code, Codex, Cursor, etc.) run directly inside your project directory. They can read, write, and edit your actual files — creating new modules in the right location, modifying existing schemas without overwriting surrounding code, and running project commands to verify output. Because they work with your real codebase rather than a copied snippet, they can stay in sync with changes you make and can handle multi-file tasks. |
There was a problem hiding this comment.
While all of this is true, I think we need to find our way to a strong recommendation of the agentic tools. The difference between asking Claude Code to add a feature to a project it can read (apostrophecms source itself included, via node_modules, I've watched it do that) is just night and day. We can point to many best practice articles on how to work more safely with them, including my own.
Also, using the chat first and then copying and pasting doesn't really keep AI-written code out of repos. There are many places to draw the line. I recommend not letting the AI commit anything to git. It's a natural place to stop and review.
| - Project-specific patterns, such as shared field groups, widget naming, reusable helpers, or migration conventions | ||
| - Common development, linting, and test commands | ||
| - Any routes, APIs, or integration points the AI tool should handle carefully | ||
| - Links to relevant internal docs or architecture notes |
There was a problem hiding this comment.
Links to the apostrophecms docs too
|
|
||
| For an ApostropheCMS project, useful things to include are: | ||
|
|
||
| - ApostropheCMS version and whether the project uses ESM or CommonJS |
There was a problem hiding this comment.
Claude Code will figure that one out quickly because it can read the source, but it can't hurt to be clear.
|
|
||
| ## Working effectively with in-project tools | ||
|
|
||
| In-project tools like Claude Code, Codex, and Cursor can do more than generate code. They can read, create, and edit files directly in your project. Taking advantage of this makes them significantly more useful than treating them as code generators. |
There was a problem hiding this comment.
Files of... code, mostly... (I think there's something here but I'm not sure it's clearly expressed)
|
|
||
| ### Use the AI to navigate the docs | ||
|
|
||
| The ApostropheCMS docs at [apostrophecms.com/docs](https://apostrophecms.com/docs) are comprehensive. In-project tools with web access can look up specifics on demand: |
There was a problem hiding this comment.
Yes, this should be in CLAUDE.md every time
|
|
||
| Many ApostropheCMS projects use ApostropheCMS with Astro handling the frontend. In these projects, ApostropheCMS still provides the Admin UI, content model, permissions, media library, page tree, URL-aware page data, and visual editing experience, while Astro handles frontend rendering through mapped templates and widgets. | ||
|
|
||
| These projects are often organized as a monorepo with separate backend and frontend apps. That split is important context for AI tools. Without it, the tool may try to solve a frontend problem in the ApostropheCMS backend, add routing to the wrong app, generate Nunjucks templates for a project that renders pages in Astro, or add direct API requests where the integration already provides the page data. |
There was a problem hiding this comment.
I would just say "are organized," it's our convention
|
|
||
| Many ApostropheCMS projects use ApostropheCMS with Astro handling the frontend. In these projects, ApostropheCMS still provides the Admin UI, content model, permissions, media library, page tree, URL-aware page data, and visual editing experience, while Astro handles frontend rendering through mapped templates and widgets. | ||
|
|
||
| These projects are often organized as a monorepo with separate backend and frontend apps. That split is important context for AI tools. Without it, the tool may try to solve a frontend problem in the ApostropheCMS backend, add routing to the wrong app, generate Nunjucks templates for a project that renders pages in Astro, or add direct API requests where the integration already provides the page data. |
| Example project instruction: | ||
|
|
||
| > This project uses ApostropheCMS with Astro as the frontend. | ||
| > The backend app is in apps/cms. The Astro frontend is in apps/frontend. |
There was a problem hiding this comment.
What is apps/? Why would it not be frontend and backend since that's what we're giving them out of the box in each starter kit?
| Example prompt: | ||
|
|
||
| > Update the article card display in the Astro frontend. Do not change the | ||
| > ApostropheCMS article schema unless a frontend field is missing. If a field is |
2 participants
Please indicate which branch this PR should merge into:
Check one
main
latest
stable
Check if this PR will be resubmitted against another branch
Summary
This PR adds basic AI usage instructions for ApostropheCMS and Astro projects. Partially closes PRO-9638.
Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
What are the specific steps to test this change?
For example:
What kind of change does this PR introduce?
(Check at least one)
Make sure the PR fulfills these requirements:
If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.
Other information: