Beginner Steps. Advanced AI.
Published guideUpdated
Chapter 8 of 20Plan
Write your website brief
Tell Codex who your website is for, what it should do, and what belongs in the first version.
Start small: who is visiting, and what do they need?
Follow the pictures
Illustrated examples. Your app may look different. Tap an image to enlarge it.
-
Name your business and audience
Use the brief example. Write who you help and what your business offers.
Illustrated example - Write
- Business → Audience → What you offer
Look for: One sentence describing your business and the people it serves.
More help with this action
Start with the example website brief. Write one sentence describing your business, its primary audience, and the problem your site should help that audience solve.
Step by step
- Open a plain-text note or ask Codex to draft a note from your words.
- Write one sentence explaining your business, the people you help, and the problem you help solve.
- Use Fieldnotes Studio only as a practice example; replace it with your own details for a real site.
You should now see: One sentence describing your business and the people it serves.
-
Choose the main visitor action
Choose one main visitor action, such as emailing you about a project.
Illustrated example - Choose
- Visitor question → Useful answer → Contact
Look for: A clear action visitors can take after reading your site.
More help with this action
Use the first-website planning questions to choose one main visitor action. For Fieldnotes Studio, this is emailing the studio about a project; list what visitors need to know first.
Step by step
- Imagine someone arriving at your site for the first time.
- Write what they need to know before contacting you: what you offer, who it helps, and how to enquire.
- For this practice site, choose an email enquiry as the main action.
You should now see: A clear action visitors can take after reading your site.
-
Pick four pages
List Home, About, Services, and Contact in the brief template. Put extra features under Later.
Illustrated example - Plan
- Home · About · Services · Contact → Later ideas
Look for: Four page names, each with one job; extra features saved for later.
More help with this action
Use the brief template to list Home, About, Services, and Contact. Give each page one purpose and put extra ideas in Later.
Step by step
- Give Home the job of introducing your offer, About the people behind it, Services the help available, and Contact the enquiry route.
- Move booking, payments, accounts, and AI chat features into Later.
- Keep the first version small enough that you can read and test every page.
You should now see: Four page names, each with one job; extra features saved for later.
-
Set your limits
Add language, content, images, timing, and your own budget to the brief template. Name the person who will maintain it.
Illustrated example - Write
- Language → Content → Budget and timing → Owner
Look for: Your own spending limit and a named website owner.
More help with this action
Add language, content, images, spending preference, timing, and maintenance ownership to the brief template. Set your own budget rather than accepting one invented by the agent.
Step by step
- Add your preferred language and the text and permitted images you already have.
- Set your own budget and target timing; do not let the agent invent a spending allowance.
- Name who will update the site, and provide a real inbox you own and can test.
You should now see: Your own spending limit and a named website owner.
-
Ask Codex to write the brief
Copy the brief prompt, replace the notes placeholder, and send it. Ask Codex to save docs/website-brief.md.
Illustrated example - Codex
- Copy prompt → Add your notes → Send → docs/website-brief.md
Look for: A brief with your notes, visible assumptions, and missing content flagged.
More help with this action
Copy the project-brief prompt, replace its notes placeholder, and send it. Ask for docs/website-brief.md with assumptions and content gaps before implementation.
Step by step
- Open the linked prompt and use Copy prompt.
- Replace the final notes placeholder with the notes you wrote in the previous actions.
- Paste into the fieldnotes-studio chat and send. The task should create docs/website-brief.md and leave building for later.
You should now see: A brief with your notes, visible assumptions, and missing content flagged.
-
Review and save it
Read the brief, correct facts, and approve the scope. Ask Codex to save a Git commit.
Illustrated example - Review
- Open brief → Correct facts → Approve scope → Commit
Look for: A saved brief you agree with, without invented claims or features.
More help with this action
Read the resulting brief, verify facts, answer essential questions, and remove unsupported features. Commit the reviewed brief to record your planning decisions.
Step by step
- Read docs/website-brief.md from beginning to end.
- Correct business facts, answer essential questions, and remove invented prices, credentials, quotes, or unsupported features.
- Ask Codex to show the changes and save the reviewed brief as a Git commit.
You should now see: A saved brief you agree with, without invented claims or features.
Why this step matters
You do not need to describe every line of code. You do need to explain who the website serves, what those visitors need, and the action you want them to take. 'Make it beautiful' leaves the agent guessing; 'help a small-business owner understand my services and contact me' gives it a useful direction.
Fieldnotes Studio is our fictional example: a small design studio seeking enquiries. Its first version has four pages and a real contact email. Accounts, payments, a booking system, and an AI chatbot are future features with separate requirements. A small complete website is easier to review and maintain.
Basics, explained
Brief
A short written agreement describing the website's purpose, audience, scope, and constraints.
Scope
The pages and features included in the version you are building.
Call to action
A clear invitation to do something, such as 'Discuss your project' or 'Email the studio'.
Assumption
Something the agent believes is true without having confirmed it. Mark assumptions so you can review them.
Ask your agent
PromptCreate your project brief
Turn my notes into docs/website-brief.md. Include purpose, primary audience, visitor needs, main call to action, four page purposes, first-version features, later features, content gaps, and constraints. Use Fieldnotes Studio as the practice example unless I provide my own business. Ask at most three essential questions; label other assumptions. Do not invent customer quotes, credentials, prices, or business claims. Do not build the website yet. My notes: [replace this sentence with your notes].Files & commands
textA brief you can adapt
Project: Fieldnotes Studio, a fictional design studio
Audience: Small-business owners considering design help
Goal: Help visitors understand our services and email us
Pages: Home / About / Services / Contact
First version: Static pages, mobile navigation, real email link
Later: Booking, payments, accounts, AI features
Content: Owner-approved copy and permitted images
Style: Calm, clear, editorial, easy to read
Budget and timing: Add your own constraints
Contact address: Provide an inbox you own and can testIf something goes wrong
- The brief grows into an elaborate app.
- Return to the single visitor action. Move features that do not support the four-page first version into 'Later' and ask Codex to update the brief.
- You are unsure what the audience needs.
- Ask someone representative of that audience what they want to know before contacting you. Bring their answers back to the brief rather than inventing a visitor profile.
Official links & further reading
Personal notes
Add questions, decisions or ideas for your website. Saved in this browser when available; export your notes to keep a copy. Never enter secrets.
Downloads & saved progressGuide, notes and personal checks
Download the complete guide or export your notes from every chapter. Instructions last reviewed: .
Checks and notes stay in this browser, separately for each language. Export your notes to preserve them. Never enter API keys or other secrets here.
NotesNotes as Markdown
Clipboard access is unavailable. Copy the visible, selected text below using your keyboard or browser menu.
0 of 65 checks marked across the guide
These are your saved personal checkmarks. They do not run tests or verify security, and are separate from the chapter position bar above.
Starter filesWorking instructions and four skills
These templates give your agent a starting set of working instructions. Review them, adapt them to your website, and save each file at the exact path shown, relative to your project folder.
A downloaded skill is an instruction file. It does not install a test runner, run a security scan, or prove your site is safe. The guide shows how to set up and check that work.
Download the instruction files in the language of this guide. Keep the technical filenames and paths as shown.
Download all starter filesFileAGENTS.md
# Website working agreements
This project follows the website brief and acceptance criteria we have agreed with its owner. Use the existing technology choices unless a concrete requirement calls for a change.
## How to work
- For a substantial feature, explain the proposed changes and verification plan before implementing it. Complete authorized local work in small, reviewable stages.
- Read the files relevant to the task. Keep unrelated pages and configuration intact.
- Explain new technical terms in plain language when reporting to the owner.
- Use the repository's website-design, clean-code, website-testing and website-security skills when their workflows apply.
- Record important decisions and unresolved content in the project's notes. Do not invent business facts, endorsements or publishing rights.
## Verification
- Inspect package.json to find the actual build, type-check and test commands. Do not invent a successful check or create a meaningless test just to make a command pass.
- Run checks appropriate to the change. Local tests use disposable fixtures and have no production access; run them and repair failures caused by the requested change without asking at every step.
- Verify visitor interactions in a browser when browser tools are available. Report checks that remain unavailable or incomplete.
- Show the owner a working local preview and summarise changed behaviour, evidence and remaining limitations.
## Credentials and publication
- Keep API keys and other secrets out of browser code, prompts, logs and Git. Store local secrets in ignored files or the chosen secret store.
- Local build and test work is authorized. Publishing the site, sending a real message, processing a payment or changing production data requires the owner's authorization for that action.
- Preserve a recoverable working version before release. Describe how to restore it.
These are starter agreements for a new tutorial project. Adapt them to the owner's actual requirements and existing authorization.
File.agents/skills/website-design/SKILL.md
---
name: website-design
description: Develop or refine a website's visual direction and responsive interface from its brief, content and existing design. Use for page design or visual implementation.
---
Read the website brief and any existing design notes relevant to the requested page. Work within the user's brand, content and technology choices.
When establishing a new direction, propose typography, a small colour palette, a spacing rhythm and a sample page. Explain how these choices support the audience and main visitor action. Use real content to judge hierarchy and line lengths.
Implement reusable elements for navigation, headings, buttons and repeated content. Give primary actions a clear visual hierarchy. Preserve visible keyboard focus, readable contrast and usable labels. Design narrow screens alongside desktop screens; check long headings, navigation and tap targets in a browser.
Use semantic HTML before adding custom interaction. Keep motion optional and respect reduced-motion preferences. Use assets with known permission to publish; record their sources. Do not invent client testimonials, achievements or business facts.
Before expanding a design across all pages, show the first complete page at desktop and mobile widths. Describe the main design decisions and any unresolved content. When a browser tool is unavailable, report that visual verification is still pending.
File.agents/skills/clean-code/SKILL.md
---
name: clean-code
description: Implement or refactor website code into understandable components using the project's existing stack and conventions. Use for website implementation or maintainability work.
---
Read the relevant files and package scripts before choosing an implementation. Preserve working behaviour outside the requested change. Prefer the existing stack and dependencies when they meet the need.
Keep page content separate from repeated layout where that makes editing easier. Name components, variables and functions for their purpose. Use shared components for repeated navigation and page elements; avoid abstraction for a single trivial use.
Handle empty, invalid, loading and error states for interactions that need them. Use native browser controls and semantic HTML when they serve the interaction. Avoid fake form submission, simulated success messages and dead links.
Use type checking and the project's formatting or lint rules where configured. When adding a package, explain its purpose and any new maintenance or runtime requirements. Keep generated build output, dependencies and local environment files out of version control.
Run the existing checks relevant to the change, including a production build when output can change. Summarise changed behaviour, verification results and remaining limits. Explain the main files in plain language so a beginner can find and edit their content.
File.agents/skills/website-testing/SKILL.md
---
name: website-testing
description: Verify website changes through visitor journeys, appropriate automated tests and browser checks. Use when testing a website, investigating a failure or preparing a release.
---
Start from the brief and observable acceptance criteria. Inspect existing test and build commands; do not assume that a script exists. Choose checks based on the changed behaviour and the cost of failure.
Exercise the main visitor journey and affected links, navigation and forms. Include invalid input and relevant error states. For a contact form, verify actual delivery in the agreed test destination before reporting that it works. For an email link, explain that it opens the visitor's configured email app and does not send a message automatically.
Check narrow and wide screens in a browser. Include keyboard navigation, visible focus, accessible names, zoom and horizontal overflow. Automated accessibility results complement these manual checks and do not establish complete accessibility conformance.
Add automated tests for important behaviour or demonstrated regressions. Test observable outcomes and meaningful failure cases; avoid tests that merely repeat the implementation or match incidental wording. Use disposable test data and local fixtures. Never send real messages, charge payments or alter production data without the user's authorization.
Reproduce a failure, fix its cause and rerun affected checks. Report commands run, results, browser checks performed and anything not checked. A successful build shows that the site can be generated; verify visitor behaviour separately. Never report a check as passed when it was skipped or unavailable.
File.agents/skills/website-security/SKILL.md
---
name: website-security
description: Review a website's secrets, dependencies, inputs, permissions and deployment configuration, and repair scoped security findings. Use for requested security review or release preparation.
---
Identify the site's relevant surfaces: static pages, forms, backend routes, authentication, third-party scripts and stored data. Scope review to the actual architecture and authorized environment.
Keep credentials out of browser code, logs, prompts and Git. Distinguish build-time public configuration from server secrets. If a key was committed or exposed, stop using it, explain that deleting the file does not revoke the key, and have the owner revoke or rotate it before further use. Do not print the credential in your report.
Inspect applicable dependency advisories and assess whether the affected package and vulnerable behaviour are used. Repair within the project's compatible versions and rerun affected checks. Avoid automatic forced upgrades that may break the website.
For backend interactions, validate inputs on the server, encode output appropriately, and check authentication and authorization separately. Consider abuse controls for public forms or AI endpoints. An OpenAI API key belongs on the server; publishing a static site does not provide a secret server environment.
Check HTTPS and applicable security headers at the actual hosting layer. Collect only the data the feature needs, and explain its destination and retention. Do not claim legal compliance from a code scan.
Report each finding with its location, plausible impact, fix and verification. State review scope, tools used, unresolved findings and inaccessible surfaces. A clean scan is evidence about that scan's scope, not a guarantee that the website has no vulnerabilities. Do not scan third-party systems or deploy changes outside the authorized task.