Add AI guide first pass by BoDonkey · Pull Request #552 · apostrophecms/docs

BoDonkey · 2026-06-29T17:32:58Z

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:

Run the website and log in as an admin

Open a piece manager modal and select several pieces

Click the "Archive" button on the top left of the manager and confirm that it should proceed

Check that all pieces have been archived properly

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

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:

linear · 2026-06-29T17:33:01Z

PRO-9638

boutell

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.

boutell · 2026-06-29T17:41:48Z

        ]
+      },
+      {
+        text: "Using AI Effectively",


Where will the title tag come from? This is fine for the sidebar, indeed

The title tag comes from the title of the piece, so (now edited) - "Using AI Coding Tools Effectively in ApostropheCMS Development"

boutell · 2026-06-29T17:44:38Z

+
+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.


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.

boutell · 2026-06-29T17:45:07Z

+- 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


Links to the apostrophecms docs too

boutell · 2026-06-29T17:45:26Z

+
+For an ApostropheCMS project, useful things to include are:
+
+- ApostropheCMS version and whether the project uses ESM or CommonJS


Claude Code will figure that one out quickly because it can read the source, but it can't hurt to be clear.

Changed a bit

boutell · 2026-06-29T17:46:08Z

+
+## 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.


Files of... code, mostly... (I think there's something here but I'm not sure it's clearly expressed)

Clarified (I hope). My point was that you can prompt for a function that does xx without context. So yeah, they are just generating code, but they can also run tests and manipulate project architecture.

boutell · 2026-06-29T17:47:44Z

+
+### 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:


Yes, this should be in CLAUDE.md every time

Tightened and clarified.

boutell · 2026-06-29T17:48:51Z

+
+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.


I would just say "are organized," it's our convention

boutell · 2026-06-29T17:49:33Z

+
+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.


Or just "are best organized"

Yeah - like this better

boutell · 2026-06-29T17:50:31Z

+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.


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?

Changed - it just felt like it was free floating or something without a root.

boutell · 2026-06-29T17:51:25Z

+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


admin UI field

Not sure what you mean, but I clarified the example.

boutell · 2026-06-30T18:31:43Z

+
+AI coding tools have a working knowledge of ApostropheCMS. The framework is well-documented, open source, and has a public GitHub history. This is enough that tools like Claude, ChatGPT, Copilot, Codex, or Cursor can often explain core concepts, describe how the module system works, or outline the difference between pieces and widgets without much help.
+
+Where things get harder is project-specific context. An AI tool has no awareness of your module structure, your schema conventions, which widgets your project uses, or whether your project is using ESM or CommonJS. It also has less training depth on ApostropheCMS than it does on higher-traffic tools and frameworks, which means it can get subtly wrong on specifics, like the exact property name for a relationship field, the right namespace for a core module, or how your project renders templates.


"it can get subtly wrong"? How about: "it can get the specifics subtly wrong"

boutell · 2026-06-30T18:32:00Z

+
+AI coding tools have a working knowledge of ApostropheCMS. The framework is well-documented, open source, and has a public GitHub history. This is enough that tools like Claude, ChatGPT, Copilot, Codex, or Cursor can often explain core concepts, describe how the module system works, or outline the difference between pieces and widgets without much help.
+
+Where things get harder is project-specific context. An AI tool has no awareness of your module structure, your schema conventions, which widgets your project uses, or whether your project is using ESM or CommonJS. It also has less training depth on ApostropheCMS than it does on higher-traffic tools and frameworks, which means it can get subtly wrong on specifics, like the exact property name for a relationship field, the right namespace for a core module, or how your project renders templates.


Or "it can be subtly wrong"

Went with the above

boutell · 2026-06-30T18:39:57Z

+
+The tradeoff is that in-project tools can act on more than you intended. They may modify files you did not expect, chain multiple actions together, or make reasonable-looking changes based on the wrong assumption.
+
+**Recommendation:** Use chat interfaces for planning, architecture questions, and explanations. Use an in-project agentic tool such as Claude Code, Codex, or Cursor for implementation work. Keep human review at the git boundary: inspect the diff, run the project’s checks, and commit the work yourself.


Chat interfaces have planning mode, and it can read your code while planning, which is a night and day, massive difference in what you'll get.

I personally think we need to turn up the recommendation for an in-project agentic tool to 100, and then give good advice on how to use it.

https://code.claude.com/docs/en/common-workflows#plan-before-editing

I think we should give explicit guidance on using planning mode with Claude Code (because we can't give gory details on a dozen tools).

Changed up and added.

boutell · 2026-06-30T18:43:46Z

+
+A developer working with the agent, for example, can then ask "create a new piece type for events" without specifying all of the above because the project instruction file has already told the tool how the project is organized.
+
+This is especially important in ApostropheCMS because two projects can organize the same feature differently. One project might define shared schema fields in helper files, another might keep all fields in the module, and another might use JSX templates instead of Nunjucks. Asking the AI to inspect nearby modules first helps it follow the project instead of generating a generic ApostropheCMS example.


Lately I'm finding Opus 4.8 will inspect the daylights out of the project before doing anything, but not everything is Opus 4.8, I realize.

Added a slight change.

boutell · 2026-06-30T18:44:16Z

+
+This is especially important in ApostropheCMS because two projects can organize the same feature differently. One project might define shared schema fields in helper files, another might keep all fields in the module, and another might use JSX templates instead of Nunjucks. Asking the AI to inspect nearby modules first helps it follow the project instead of generating a generic ApostropheCMS example.
+
+For new projects, start with the ApostropheCMS CLI whenever possible (`npm create apostrophe@latest`). The CLI can create both traditional ApostropheCMS projects and Astro-based projects from official starter kits, giving you a structure that matches the documentation and examples. For Astro projects, this is especially helpful because the generated project already includes the expected frontend/backend split, Astro integration setup, template and widget mappings, and visual editing patterns. That helps both developers and AI tools find the right files, follow expected conventions, and avoid inventing project structure.


unless you are forking a preexisting project of your own

Added in the caveat.

boutell · 2026-06-30T18:50:15Z

+- generating Nunjucks examples for a JSX project, or JSX examples for a Nunjucks project
+- treating ApostropheCMS like a generic Express app instead of using its module system
+
+These are good reasons to keep the ApostropheCMS docs, project-specific conventions, and nearby working examples in the tool's context.


And, using an agentic tool means that the project itself will constantly be there to provide context and keep the AI on the rails.

boutell · 2026-06-30T18:52:44Z

+> mapping patterns. Do not add direct REST API calls unless the existing project
+> already uses them for this feature.
+
+Useful integration-specific files to point the AI toward include:


For better results right off the bat, launch your agentic AI tool in the main project directory, where it can see both the Astro frontend and ApostropheCMS backend subdirectories. This provides quite a bit of context "for free" even before you provide specific guidance.

boutell · 2026-06-30T18:55:20Z

+- related templates, helpers, or frontend components were updated only where needed
+- linting, tests, or build checks pass when available
+
+AI tools are most useful when they help you move faster through work you still understand. If you cannot explain the change, ask the tool to walk through it before you accept it.


One common pattern is to refuse permission when Claude Code and similar tools ask to use git on their own. Instead, hold that privilege back for yourself. This provides a natural opportunity to read git diff and look for issues before committing.

boutell · 2026-06-30T18:57:27Z

+- related templates, helpers, or frontend components were updated only where needed
+- linting, tests, or build checks pass when available
+
+AI tools are most useful when they help you move faster through work you still understand. If you cannot explain the change, ask the tool to walk through it before you accept it.


Debugging with agentic tools

Claude Code and similar tools can do quite a bit to help debug your site. If you encourage them to install the playwright module, and then require them to use it to directly view the site, they can debug issues visually and interactively. This can even include logging in and taking actions as a user, if you're building a feature that requires that.

boutell · 2026-06-30T18:59:17Z

+
+**Recommendation:** Use chat interfaces for planning, architecture questions, and explanations. Use an in-project agentic tool such as Claude Code, Codex, or Cursor for implementation work. Keep human review at the git boundary: inspect the diff, run the project’s checks, and commit the work yourself.
+
+## Give AI tools persistent project context


Watch out for the "free tier" of AI models. Unfortunately, you sometimes get what you pay for. The models available at no charge usually are limited to the chat window only and are much more likely to give shallow and incomplete or incorrect answers. A "Pro" account in the $20/month range is more than worthwhile for serious AI-accelerated development.

Add AI guide first pass

5825961

BoDonkey requested a review from boutell June 29, 2026 17:32

boutell requested changes Jun 29, 2026

View reviewed changes

Response to first comments

1116ad5

BoDonkey requested a review from boutell June 30, 2026 14:21

boutell requested changes Jun 30, 2026

View reviewed changes

BoDonkey added 2 commits July 6, 2026 11:27

Fix quote type

11b1e9f

Responses to second review

59aba25

BoDonkey requested a review from boutell July 7, 2026 19:19


		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.


		For an ApostropheCMS project, useful things to include are:

		- ApostropheCMS version and whether the project uses ESM or CommonJS


		## 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.


		### 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:


		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.


		AI coding tools have a working knowledge of ApostropheCMS. The framework is well-documented, open source, and has a public GitHub history. This is enough that tools like Claude, ChatGPT, Copilot, Codex, or Cursor can often explain core concepts, describe how the module system works, or outline the difference between pieces and widgets without much help.

		Where things get harder is project-specific context. An AI tool has no awareness of your module structure, your schema conventions, which widgets your project uses, or whether your project is using ESM or CommonJS. It also has less training depth on ApostropheCMS than it does on higher-traffic tools and frameworks, which means it can get subtly wrong on specifics, like the exact property name for a relationship field, the right namespace for a core module, or how your project renders templates.


		The tradeoff is that in-project tools can act on more than you intended. They may modify files you did not expect, chain multiple actions together, or make reasonable-looking changes based on the wrong assumption.

		Recommendation: Use chat interfaces for planning, architecture questions, and explanations. Use an in-project agentic tool such as Claude Code, Codex, or Cursor for implementation work. Keep human review at the git boundary: inspect the diff, run the project’s checks, and commit the work yourself.


		A developer working with the agent, for example, can then ask "create a new piece type for events" without specifying all of the above because the project instruction file has already told the tool how the project is organized.

		This is especially important in ApostropheCMS because two projects can organize the same feature differently. One project might define shared schema fields in helper files, another might keep all fields in the module, and another might use JSX templates instead of Nunjucks. Asking the AI to inspect nearby modules first helps it follow the project instead of generating a generic ApostropheCMS example.


		This is especially important in ApostropheCMS because two projects can organize the same feature differently. One project might define shared schema fields in helper files, another might keep all fields in the module, and another might use JSX templates instead of Nunjucks. Asking the AI to inspect nearby modules first helps it follow the project instead of generating a generic ApostropheCMS example.

		For new projects, start with the ApostropheCMS CLI whenever possible (`npm create apostrophe@latest`). The CLI can create both traditional ApostropheCMS projects and Astro-based projects from official starter kits, giving you a structure that matches the documentation and examples. For Astro projects, this is especially helpful because the generated project already includes the expected frontend/backend split, Astro integration setup, template and widget mappings, and visual editing patterns. That helps both developers and AI tools find the right files, follow expected conventions, and avoid inventing project structure.


		Recommendation: Use chat interfaces for planning, architecture questions, and explanations. Use an in-project agentic tool such as Claude Code, Codex, or Cursor for implementation work. Keep human review at the git boundary: inspect the diff, run the project’s checks, and commit the work yourself.

		## Give AI tools persistent project context

Uh oh!

Conversation

BoDonkey commented Jun 29, 2026

Please indicate which branch this PR should merge into:

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

linear Bot commented Jun 29, 2026

Uh oh!

boutell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!