Custom instructions

Always-on guidance the agent follows across every prompt. Coding style, brand voice, defaults — set once, applied everywhere.

Custom instructions are rules the agent follows on every prompt. Use them for things you’d otherwise restate in every prompt: coding style preferences, default behaviors, things to never do.

Where they live

Scope	Where	Applies to
Workspace-wide	Workspace settings → Custom instructions	Every project in the workspace
Project-specific	Project settings → Custom instructions	This project only

Project-specific instructions override workspace-wide on conflicts.

Examples

Coding style

- Use named functions, not arrow functions, for top-level components
- Prefer for-of over forEach
- Never use `any` in TypeScript; if you need an escape hatch, use `unknown` and narrow
- File names: kebab-case
- Imports: external first, then internal absolute, then relative — alphabetized within each group

Brand and copy

- Tone is warm but professional. Don't use exclamation marks.
- Refer to ourselves as "we" not "the company"
- All currency is USD; format with Intl.NumberFormat, two decimals
- Dates: full month name + day + year ("April 18, 2026"), not numeric

Defaults

- All forms use react-hook-form + zod for validation
- All toasts come from sonner, with the default duration 5 seconds
- All loading states use the shared <Skeleton /> component, not spinners

Don’ts

- Don't add tests unless I explicitly ask
- Don't add TODO comments — open a tracking task instead
- Don't reformat or refactor code that's not part of the prompt
- Don't add console.log statements in production code paths

Anatomy of a good instruction

✅ Specific and actionable

“Use 4-space indentation in TypeScript files.” Verifiable.

✅ Reasoned (when non-obvious)

“Prefer Convex actions over fetch() in components — it keeps API calls server-side.” The ‘why’ helps the agent generalize.

❌ Vague

“Write good code.” Unactionable.

❌ Contradictory

“Use functional components” + “Always use class components for forms”. Pick one.

Workspace-wide vs. project-specific

Use workspace-wide for rules that apply to all your work: coding style, naming conventions, etc.

Use project-specific for rules tied to one app: “This project uses Tailwind v4. The brand color is #FF6600. Reference the design system at https://design.thisapp.com.”

Tips

Start small. Add as you correct. Every time you reverse a vly decision, ask: “Could a custom instruction prevent this next time?” If yes, add it.

Use Markdown. Custom instructions are parsed as markdown. Use bullets, code blocks, and headers for clarity.

Don’t replicate the knowledge base. Custom instructions are rules. Knowledge is reference. If it’s a fact (“our color is #6D28D9”), it’s knowledge. If it’s an action (“use this color”), it’s an instruction.

Related

Knowledge base

Reference material the agent reads.

Templates

Pre-built starting points.

Prompting fundamentals

The basics of writing a prompt.