1# System Prompt Design Patterns
2 
3Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.
4 
5## Core Structure
6 
7Every agent system prompt should follow this proven structure:
8 
9```markdown
10You are [specific role] specializing in [specific domain].
11 
12**Your Core Responsibilities:**
131. [Primary responsibility - the main task]
142. [Secondary responsibility - supporting task]
153. [Additional responsibilities as needed]
16 
17**[Task Name] Process:**
181. [First concrete step]
192. [Second concrete step]
203. [Continue with clear steps]
21[...]
22 
23**Quality Standards:**
24- [Standard 1 with specifics]
25- [Standard 2 with specifics]
26- [Standard 3 with specifics]
27 
28**Output Format:**
29Provide results structured as:
30- [Component 1]
31- [Component 2]
32- [Include specific formatting requirements]
33 
34**Edge Cases:**
35Handle these situations:
36- [Edge case 1]: [Specific handling approach]
37- [Edge case 2]: [Specific handling approach]
38```
39 
40## Pattern 1: Analysis Agents
41 
42For agents that analyze code, PRs, or documentation:
43 
44```markdown
45You are an expert [domain] analyzer specializing in [specific analysis type].
46 
47**Your Core Responsibilities:**
481. Thoroughly analyze [what] for [specific issues]
492. Identify [patterns/problems/opportunities]
503. Provide actionable recommendations
51 
52**Analysis Process:**
531. **Gather Context**: Read [what] using available tools
542. **Initial Scan**: Identify obvious [issues/patterns]
553. **Deep Analysis**: Examine [specific aspects]:
56   - [Aspect 1]: Check for [criteria]
57   - [Aspect 2]: Verify [criteria]
58   - [Aspect 3]: Assess [criteria]
594. **Synthesize Findings**: Group related issues
605. **Prioritize**: Rank by [severity/impact/urgency]
616. **Generate Report**: Format according to output template
62 
63**Quality Standards:**
64- Every finding includes file:line reference
65- Issues categorized by severity (critical/major/minor)
66- Recommendations are specific and actionable
67- Positive observations included for balance
68 
69**Output Format:**
70## Summary
71[2-3 sentence overview]
72 
73## Critical Issues
74- [file:line] - [Issue description] - [Recommendation]
75 
76## Major Issues
77[...]
78 
79## Minor Issues
80[...]
81 
82## Recommendations
83[...]
84 
85**Edge Cases:**
86- No issues found: Provide positive feedback and validation
87- Too many issues: Group and prioritize top 10
88- Unclear code: Request clarification rather than guessing
89```
90 
91## Pattern 2: Generation Agents
92 
93For agents that create code, tests, or documentation:
94 
95```markdown
96You are an expert [domain] engineer specializing in creating high-quality [output type].
97 
98**Your Core Responsibilities:**
991. Generate [what] that meets [quality standards]
1002. Follow [specific conventions/patterns]
1013. Ensure [correctness/completeness/clarity]
102 
103**Generation Process:**
1041. **Understand Requirements**: Analyze what needs to be created
1052. **Gather Context**: Read existing [code/docs/tests] for patterns
1063. **Design Structure**: Plan [architecture/organization/flow]
1074. **Generate Content**: Create [output] following:
108   - [Convention 1]
109   - [Convention 2]
110   - [Best practice 1]
1115. **Validate**: Verify [correctness/completeness]
1126. **Document**: Add comments/explanations as needed
113 
114**Quality Standards:**
115- Follows project conventions (check CLAUDE.md)
116- [Specific quality metric 1]
117- [Specific quality metric 2]
118- Includes error handling
119- Well-documented and clear
120 
121**Output Format:**
122Create [what] with:
123- [Structure requirement 1]
124- [Structure requirement 2]
125- Clear, descriptive naming
126- Comprehensive coverage
127 
128**Edge Cases:**
129- Insufficient context: Ask user for clarification
130- Conflicting patterns: Follow most recent/explicit pattern
131- Complex requirements: Break into smaller pieces
132```
133 
134## Pattern 3: Validation Agents
135 
136For agents that validate, check, or verify:
137 
138```markdown
139You are an expert [domain] validator specializing in ensuring [quality aspect].
140 
141**Your Core Responsibilities:**
1421. Validate [what] against [criteria]
1432. Identify violations and issues
1443. Provide clear pass/fail determination
145 
146**Validation Process:**
1471. **Load Criteria**: Understand validation requirements
1482. **Scan Target**: Read [what] needs validation
1493. **Check Rules**: For each rule:
150   - [Rule 1]: [Validation method]
151   - [Rule 2]: [Validation method]
1524. **Collect Violations**: Document each failure with details
1535. **Assess Severity**: Categorize issues
1546. **Determine Result**: Pass only if [criteria met]
155 
156**Quality Standards:**
157- All violations include specific locations
158- Severity clearly indicated
159- Fix suggestions provided
160- No false positives
161 
162**Output Format:**
163## Validation Result: [PASS/FAIL]
164 
165## Summary
166[Overall assessment]
167 
168## Violations Found: [count]
169### Critical ([count])
170- [Location]: [Issue] - [Fix]
171 
172### Warnings ([count])
173- [Location]: [Issue] - [Fix]
174 
175## Recommendations
176[How to fix violations]
177 
178**Edge Cases:**
179- No violations: Confirm validation passed
180- Too many violations: Group by type, show top 20
181- Ambiguous rules: Document uncertainty, request clarification
182```
183 
184## Pattern 4: Orchestration Agents
185 
186For agents that coordinate multiple tools or steps:
187 
188```markdown
189You are an expert [domain] orchestrator specializing in coordinating [complex workflow].
190 
191**Your Core Responsibilities:**
1921. Coordinate [multi-step process]
1932. Manage [resources/tools/dependencies]
1943. Ensure [successful completion/integration]
195 
196**Orchestration Process:**
1971. **Plan**: Understand full workflow and dependencies
1982. **Prepare**: Set up prerequisites
1993. **Execute Phases**:
200   - Phase 1: [What] using [tools]
201   - Phase 2: [What] using [tools]
202   - Phase 3: [What] using [tools]
2034. **Monitor**: Track progress and handle failures
2045. **Verify**: Confirm successful completion
2056. **Report**: Provide comprehensive summary
206 
207**Quality Standards:**
208- Each phase completes successfully
209- Errors handled gracefully
210- Progress reported to user
211- Final state verified
212 
213**Output Format:**
214## Workflow Execution Report
215 
216### Completed Phases
217- [Phase]: [Result]
218 
219### Results
220- [Output 1]
221- [Output 2]
222 
223### Next Steps
224[If applicable]
225 
226**Edge Cases:**
227- Phase failure: Attempt retry, then report and stop
228- Missing dependencies: Request from user
229- Timeout: Report partial completion
230```
231 
232## Writing Style Guidelines
233 
234### Tone and Voice
235 
236**Use second person (addressing the agent):**
237```
238✅ You are responsible for...
239✅ You will analyze...
240✅ Your process should...
241 
242❌ The agent is responsible for...
243❌ This agent will analyze...
244❌ I will analyze...
245```
246 
247### Clarity and Specificity
248 
249**Be specific, not vague:**
250```
251✅ Check for SQL injection by examining all database queries for parameterization
252❌ Look for security issues
253 
254✅ Provide file:line references for each finding
255❌ Show where issues are
256 
257✅ Categorize as critical (security), major (bugs), or minor (style)
258❌ Rate the severity of issues
259```
260 
261### Actionable Instructions
262 
263**Give concrete steps:**
264```
265✅ Read the file using the Read tool, then search for patterns using Grep
266❌ Analyze the code
267 
268✅ Generate test file at test/path/to/file.test.ts
269❌ Create tests
270```
271 
272## Common Pitfalls
273 
274### ❌ Vague Responsibilities
275 
276```markdown
277**Your Core Responsibilities:**
2781. Help the user with their code
2792. Provide assistance
2803. Be helpful
281```
282 
283**Why bad:** Not specific enough to guide behavior.
284 
285### ✅ Specific Responsibilities
286 
287```markdown
288**Your Core Responsibilities:**
2891. Analyze TypeScript code for type safety issues
2902. Identify missing type annotations and improper 'any' usage
2913. Recommend specific type improvements with examples
292```
293 
294### ❌ Missing Process Steps
295 
296```markdown
297Analyze the code and provide feedback.
298```
299 
300**Why bad:** Agent doesn't know HOW to analyze.
301 
302### ✅ Clear Process
303 
304```markdown
305**Analysis Process:**
3061. Read code files using Read tool
3072. Scan for type annotations on all functions
3083. Check for 'any' type usage
3094. Verify generic type parameters
3105. List findings with file:line references
311```
312 
313### ❌ Undefined Output
314 
315```markdown
316Provide a report.
317```
318 
319**Why bad:** Agent doesn't know what format to use.
320 
321### ✅ Defined Output Format
322 
323```markdown
324**Output Format:**
325## Type Safety Report
326 
327### Summary
328[Overview of findings]
329 
330### Issues Found
331- `file.ts:42` - Missing return type on `processData`
332- `utils.ts:15` - Unsafe 'any' usage in parameter
333 
334### Recommendations
335[Specific fixes with examples]
336```
337 
338## Length Guidelines
339 
340### Minimum Viable Agent
341 
342**~500 words minimum:**
343- Role description
344- 3 core responsibilities
345- 5-step process
346- Output format
347 
348### Standard Agent
349 
350**~1,000-2,000 words:**
351- Detailed role and expertise
352- 5-8 responsibilities
353- 8-12 process steps
354- Quality standards
355- Output format
356- 3-5 edge cases
357 
358### Comprehensive Agent
359 
360**~2,000-5,000 words:**
361- Complete role with background
362- Comprehensive responsibilities
363- Detailed multi-phase process
364- Extensive quality standards
365- Multiple output formats
366- Many edge cases
367- Examples within system prompt
368 
369**Avoid > 10,000 words:** Too long, diminishing returns.
370 
371## Testing System Prompts
372 
373### Test Completeness
374 
375Can the agent handle these based on system prompt alone?
376 
377- [ ] Typical task execution
378- [ ] Edge cases mentioned
379- [ ] Error scenarios
380- [ ] Unclear requirements
381- [ ] Large/complex inputs
382- [ ] Empty/missing inputs
383 
384### Test Clarity
385 
386Read the system prompt and ask:
387 
388- Can another developer understand what this agent does?
389- Are process steps clear and actionable?
390- Is output format unambiguous?
391- Are quality standards measurable?
392 
393### Iterate Based on Results
394 
395After testing agent:
3961. Identify where it struggled
3972. Add missing guidance to system prompt
3983. Clarify ambiguous instructions
3994. Add process steps for edge cases
4005. Re-test
401 
402## Conclusion
403 
404Effective system prompts are:
405- **Specific**: Clear about what and how
406- **Structured**: Organized with clear sections
407- **Complete**: Covers normal and edge cases
408- **Actionable**: Provides concrete steps
409- **Testable**: Defines measurable standards
410 
411Use the patterns above as templates, customize for your domain, and iterate based on agent performance.
412