What you get from the AI depends mostly on what you ask. It does what you said, not what you meant, so the skill that makes the difference isn't technical: it's describing with precision. These habits work for any Velk request.
The briefing
The briefing is the description you give before anything is built. Three things always go in it:
- The business, not only the kind of site. “A neighborhood bakery that takes cake orders” produces better fields and sample texts than “an institutional site”.
- The fields, by name. Instead of “a testimonials section”, say “testimonials, each with the text, the person's name and their company”. With that, you've designed the panel.
- What's out, for now. “Only Home, About and Contact for now” stops the AI from inventing a blog or a store you didn't ask for, which would take work to remove.
Describe the information, not the look: “a list of services, each with a name and a summary” beats “a nice services section”.
Ask the AI
Create the structure of a site for Padaria Aurora, a neighborhood bakery in Curitiba that takes cake orders. Pages for now: Home, About and Contact. The Home needs: - a short line above the title - a main title - an intro paragraph - the button text - a list of products, each with a name, a one-line description and a photo About and Contact are simple pages: title, intro and a formatted text. No blog, store or members area yet. Show me the field names before writing anything, and validate at the end.
Each line of the list becomes a field the client edits in the panel.
Page or content type?
A page is unique (one Home, one About) with its own fields and a fixed address. A content type is plural and grows: posts, cases, services, all with the same fields, created by the client without calling you. One question decides it: will the client want to create another one of these alone? If yes, it's a content type. Getting it wrong is the most common structural mistake, and the most expensive to fix later. When you ask for a content type, give its plural name and its address (“Cases, at /cases”), or the AI will guess.
Review before you approve
Read what the AI proposes before you say yes, above all the field names. A field has a label, the text the editor reads, which you can change any time, and a name, the internal key the templates use. Renaming a field once there's content leaves the old values stranded under the old name, so the first review is the last cheap moment to get names right.
The Claude app can make the AI wait for you: a mode selector next to the message box decides how much it does without asking. The names may change between versions of the app; what each mode does is what counts.
The permission modes
| Mode | What it does, and when to use it |
|---|---|
| Manual | Asks before every change. Use it while you're learning: you see each change before it happens, and that's how you learn what Velk is doing. |
| Plan | Writes a plan before touching anything. Use it for big requests, such as the whole structure of a site: you correct the plan instead of undoing the result. |
| Accept edits | Applies file changes without asking. For repetitive work you've already checked. |
| Automatic | Decides by itself what it can do. When you trust the flow and want speed. |
Check every change
- Validate. After any change to
site.json, ask forschema:validate. It points out structure errors at once (and, since v3.9.0, lists templates the theme is missing) instead of leaving a broken page for next week. - Look at it. A passing check isn't the end. Open the page on the site and the screen in the panel, confirm the field shows and saves, and look at it on a phone. On a multi-language site, check each language.
- One part at a time. Ask, review, check, then move on. Small steps make it clear which request changed what.
Ask the AI
On the Home, add a testimonial section with the text, the person's name and their company. Validate the site.json and tell me where it shows up in the panel.
The everyday loop: ask with the information to keep, review the names, check the site and the panel.
When something goes wrong
Describe it as you would to a colleague: the symptom, where it happens and what changed last. “Since I updated the engine, the contact page shows error 500” takes the AI straight to the right place; “the site broke” doesn't. When you're unsure, ask it to explain before it changes anything.
Patterns worth reusing
| Pattern | Example |
|---|---|
| Explain first | “Before changing anything, tell me which files you'd touch and why.” |
| Limit the scope | “Change only the footer. Don't touch the header or the Home.” |
| Ask for options | “Give me two ways to organize the services, with the pros and cons of each.” |
| Point at what you see | “On a phone, the menu covers the logo on the Contact page.” |
| Ask for proof | “Open the page and confirm the new section shows in both languages.” |