Custom Prompts

The system_prompt setting lets you give the reviewer additional instructions tailored to your environment, your codebase, and the kinds of mistakes you've seen. This is the most direct way to make the reviewer useful — a generic reviewer catches generic problems, but a reviewer that knows what to look for catches the problems that actually matter to you.

Why you should customize the prompt

The default reviewer profile is general-purpose. It catches a broad class of issues — dangerous shell commands, sloppy file writes, premature stops — but it doesn't know about your specific codebase, your team's conventions, or the patterns you've seen agents get wrong.

If you've noticed the agent consistently:

• Reaches for client-side state when the component should be a server component
• Installs new dependencies for things already in your stack
• Writes tests that only cover the happy path and skip the edge cases that actually break
• Over-abstracts — wraps three lines in a utility function nobody will ever reuse
• Makes unsourced claims in research or documentation tasks

...then tell the reviewer to watch for those things. The reviewer can only catch what it knows to look for.

Configuration

defaults:
  system_prompt: |
    This is a Next.js 15 app using the App Router. The agent tends to
    add "use client" to components that don't need it. Flag any component
    that uses "use client" without actually using hooks, event handlers,
    or browser APIs — it should be a server component.
  system_prompt_mode: append

Key	Type	Default	Description
system_prompt	string	—	Your custom instructions for the reviewer
system_prompt_mode	string	"replace"	How your prompt combines with the server profile's prompt

Replace vs. append

The system_prompt_mode controls how your custom prompt interacts with the server-side profile prompt:

append (recommended) — Your prompt is added to the end of the server profile's prompt. The reviewer gets the full default behavioral instructions plus your additions. Use this when you want to keep the default review behavior and layer your own rules on top.

replace — Your prompt replaces the server profile's prompt entirely. The reviewer only gets your instructions. Use this when you want full control over the reviewer's behavior and don't want the default profile influencing it.

Start with append

Unless you have a specific reason to replace the entire prompt, use append. The server profile contains tested behavioral instructions that handle common review scenarios. Your custom prompt works best as additional focus areas layered on top.

Examples

Codebase conventions

defaults:
  system_prompt: |
    We use Tailwind v4 with the new CSS-first config. The agent keeps
    generating tailwind.config.js files and using the old @apply syntax.
    Flag any Tailwind config in JS/TS — configuration belongs in CSS.

    All data fetching goes through our internal API client at lib/api.ts.
    Don't let the agent use raw fetch() or install axios.
  system_prompt_mode: append

Architecture guardrails

defaults:
  system_prompt: |
    This is a monorepo with strict package boundaries. Watch for:
    - Direct imports across package boundaries (should go through the public API)
    - Shared types duplicated instead of imported from @repo/types
    - Environment variables accessed outside of lib/env.ts
    - Any new dependency added to the root package.json instead of the specific package
  system_prompt_mode: append

Agent behavior patterns

defaults:
  system_prompt: |
    The agent tends to over-engineer. If it creates a wrapper, helper,
    or abstraction that's only used in one place, flag it. Three similar
    lines is better than a premature abstraction.

    It also adds defensive error handling for things that can't fail.
    Don't let it wrap internal function calls in try/catch — only
    validate at system boundaries (user input, API responses, file I/O).
  system_prompt_mode: append

Beyond code

Zwischen reviews the agent's entire output — not just code. If your agent does research, writes documentation, or generates content, you can tune the reviewer for that too.

defaults:
  system_prompt: |
    The agent is writing user-facing documentation. Watch for:
    - Claims without evidence or citations — don't let it state things
      as fact unless it has a source
    - Weasel words ("generally", "typically", "in most cases") used to
      hedge around things it doesn't actually know
    - Placeholder content or TODO markers left in finished output
    - Inconsistent terminology — if we call it a "workspace" in one
      place, don't let it say "project" in another
  system_prompt_mode: append

Per-profile prompts

Different agents can get different prompts via profiles:

profiles:
  frontend:
    agents: [coder, web-dev]
    system_prompt: |
      Focus on accessibility and performance. Flag any interactive
      element without an aria-label. Flag any image without alt text.
      Flag any useEffect that runs on every render without a
      dependency array.
    system_prompt_mode: append

  orchestrator:
    agents: [orchestrator]
    system_prompt: |
      The orchestrator delegates to subagents. Watch for tasks being
      delegated without enough context — the subagent should always
      get file paths, specific requirements, and success criteria.
      Don't let it fire-and-forget.
    system_prompt_mode: append

Prompt tips

Be specific. "Watch for bad code" gives the reviewer nothing to work with. "Flag any component that imports from @mui/material — we migrated to Radix and shadcn" gives it a concrete rule.

Describe the pattern, not just the symptom. Instead of "the agent writes bad tests," say "the agent generates tests that only cover the happy path — it never tests error conditions, edge cases, or boundary values."

Include context the reviewer wouldn't have. The reviewer can see your code but doesn't know your deployment environment, your team's conventions, or what broke last week. Tell it.

Keep it focused. A prompt with 3 specific, well-described patterns is more effective than a prompt with 20 vague ones. The reviewer has finite attention — don't dilute it.

Inheritance

system_prompt does not deep-merge between defaults and profiles. A profile's system_prompt is used as-is — it does not inherit from or append to the defaults.system_prompt. The system_prompt_mode controls how the custom prompt interacts with the server profile's base prompt, not with defaults.

If you set a system_prompt in both defaults and a profile, agents matching that profile will only see the profile's prompt (combined with the server profile per system_prompt_mode). The defaults prompt is ignored for those agents.