Lesson 1: Custom Agent Prompts

Why Custom Prompts Matter

The default ReArch agent prompt is a good starting point, but every codebase has its own conventions, patterns, and quirks. Custom prompts let you encode this tribal knowledge so the agent produces code that looks like it was written by your team.

Prompt Anatomy

A system prompt has four sections:

# Role

You are a senior TypeScript developer working on a Next.js 14 e-commerce application.

# Conventions

- Use functional components with hooks (no class components)
- All components must have co-located unit tests using Vitest
- Use Tailwind CSS for styling, never inline styles
- Follow the existing naming: PascalCase for components, camelCase for utilities

# Constraints

- Do NOT add new dependencies without explicit approval
- Do NOT modify files in src/core/ — those are owned by the platform team
- Always run `pnpm lint` before committing

# Output Format

- Provide a brief summary of changes before the code
- Include code comments only where logic is non-obvious

Role

Defines who the agent is. This shapes the overall tone and expertise level. Be specific — “senior TypeScript developer” produces different output than “developer”.

Conventions

Your team’s coding standards. The agent will follow these consistently, even across dozens of files. This is where you get the biggest return on investment.

Constraints

Hard rules the agent must not break. Think of these as guardrails. If the agent violates a constraint, you will see it in review.

Output Format

Controls how the agent structures its responses and code. Useful for enforcing documentation standards.

Managing Prompts

Prompts live in .rearch/prompts/:

.rearch/prompts/
├── default.md           # Used when no prompt is specified
├── feature.md           # For feature development tasks
├── bugfix.md            # For bug fix tasks
├── refactor.md          # For refactoring tasks
└── docs.md              # For documentation tasks

Assign a prompt to a pipeline:

.rearch/pipelines/feature.yaml

pipeline:
  name: feature
  prompt: feature # Uses .rearch/prompts/feature.md
  steps:
    - explore
    - plan
    - implement
    - test
    - pr

Prompt Variables

Use variables to inject dynamic context:

# Role

You are working on the {{project.name}} project, which uses {{project.framework}}.

# Current Task

{{task.description}}

# Relevant Files

{{task.constraints.files}}

Available variables:

Variable	Description
{{project.name}}	Project name from config
{{project.language}}	Primary language
{{project.framework}}	Detected framework
{{task.description}}	Current task description
{{task.constraints.*}}	Task constraint values
{{git.branch}}	Current branch name
{{git.recent_commits}}	Last 5 commit messages

Iterating on Prompts

Prompt engineering is iterative. Here is a practical workflow:

1. Start with the default — run a few tasks and review the output
2. Identify patterns — what does the agent get wrong consistently?
3. Add conventions — encode fixes as conventions in your prompt
4. Test — run the same task again and compare
5. Refine — repeat until the output matches your standards

Example: Fixing a Common Issue

The agent keeps using index.ts barrel exports, but your team avoids them:

# Conventions (add this line)

- Do NOT create index.ts barrel files. Import directly from the source file.

One line. Run the same task again — the barrel files disappear.

What’s Next

In the next lesson, you will learn how to coordinate ReArch across multiple repositories for monorepo and multi-repo setups.

---