# The AI Workflow
## The AI Workflow
**Skill level:** Beginner · **Time:** 5 minutes to set up
The same loop works for every change: **save a checkpoint → ask → review → check → keep or undo.**
For Cursor, Windsurf, Claude Code, GitHub Copilot in VS Code, Gemini CLI, Codex, and similar tools.
1. **Open the whole Margo project folder** in the tool (the folder with `package.json`), not a single file or the unzipped download around it. The tool needs that folder to find `AGENTS.md` and its own rules file.
2. **Start the site** with `npm run dev` so you can watch the change happen at [http://localhost:4321/](http://localhost:4321/).
3. **Save a checkpoint.** If you use git, commit. If not, copy the folder. See [Editing Safely](/margo/beginner/editing-safely/).
4. **Ask for one change.** Name the file if you know it. Start your first request with "Read AGENTS.md first." Most tools load it on their own, and the sentence costs nothing in the others. For a bigger job, add "Follow the matching recipe in SKILLS.md." The [Prompt Library](/margo/ai-customization/prompt-library/) has ready-made requests.
5. **Review what changed.** Every tool shows a list of edited files and the changes ("diff"). Check them against the review checklist below before you accept.
6. **Check the result** in the browser. `npm run dev` picks up a saved change to `config.toml` on its own. Restart it after you change `fonts.json`, `trailingSlash`, or anything in `[settings.multilingual]`: Astro reads those only when it starts. Ask the assistant to run `npm run astro-check`, or run it yourself.
7. **Keep it or undo it.** Commit if you are happy. If not, ask the tool to revert, or restore your checkpoint.
For ChatGPT, Claude, Gemini, or any assistant in a browser tab.
1. **Give it the rules once per conversation.** Open `AGENTS.md` in your editor, copy all of it, and paste it with: "These are the rules of the website theme I'm editing. Follow them in every answer."
2. **Paste the file you want to change**, with its path. For example: "Here is `src/content/sections/english/hero-section.md`:" and the whole file.
3. **Ask for the change and the full file back**: "Return the complete file, ready to paste, and change nothing else."
4. **Paste the answer over the file** in your editor and save.
5. **Check the result** in the browser. If the terminal shows an error, copy the error and paste it back into the chat.
Chat assistants work best for text: rewriting copy, translating, writing journal posts, project stories, and service descriptions. For a change that touches several files, such as a new project (the project file in each language, its photos, and maybe a menu link), an AI editor saves a lot of copying.
### Give The AI Good Context
The more precise the request, the better the result. Useful things to include:
- **The file.** "Edit `src/content/projects/english/ceramic-forms.md`", not "edit the first project".
- **The page.** "The section under the hero on `/home-studio/`."
- **About you.** One paragraph: what you make, for whom, where you work, and how you like to work. Paste it into every copywriting request.
- **Your real facts.** Client names, years, results, prices, quotes you have permission to use. If you don't give them, tell the assistant to keep the sample values and list them for you to replace.
- **The layout name.** Copy it from the comment next to `layout:` in the section file: "use the `panel` layout of the hero".
- **What must not change.** "Keep every key, id, and the number of items." Ids such as `ceramic-forms` or `brand-identity` link files together: a project file, the hero cards that list it, the services that show it as related work, and the menu.
### Review Checklist
Before you accept a change, check:
- [ ] Only the files you expected were edited.
- [ ] Text was changed in `src/content/`, `src/config/`, or `src/i18n/`, not typed into a component.
- [ ] Every language you keep was updated: each language folder, `src/i18n/.json`, and `src/config/menu..json` (unless you turned a language off).
- [ ] Keys, ids, and indentation in Markdown frontmatter, TOML, and JSON still look like the rest of the file.
- [ ] No new colors like `text-[#123456]` in components. Margo uses its theme tokens (`text-ink`, `bg-paper`, `border-line`).
- [ ] No testimonials, ratings, review counts, client names, metrics, or prices were made up. Where you didn't provide them, the assistant kept the sample items and told you which ones to replace.
- [ ] `npm run astro-check` reports no errors.
- [ ] The changed pages look right in the browser:
- at about **375 px** wide (a phone) and at **1280 px**
- in **light and dark** mode (the light/dark button in the header, or in the mobile menu)
- in **every language** (the language switch, or `/fr/` or `/ar/` in front of the path). Arabic pages should read right to left
`astro-check` doesn't validate the files in `src/content/sections/`, `src/content/contact/`, `src/content/faq/`, and `src/content/pricing/`, and a misnamed page block is ignored without an error. Only the page shows those mistakes.
### When The AI Gets Stuck
- **There is an error in the terminal.** Copy the whole error, including the file name and line number, and paste it with: "Fix this error. Explain the cause in one sentence."
- **The change does nothing.** Ask: "Which file does this text come from on this page? Check the route, the page's named block, and the section file." A page block overrides the section file (see [How Margo Works](/margo/getting-started/how-margo-works/)). If the change is in `config.toml`, check the terminal for `[toml-watcher]` lines, or restart `npm run dev`.
- **It keeps going in circles.** Undo to your checkpoint, start a new conversation, and ask for a smaller step.