surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / agent-development / references / system-prompt-design.md

411 lines · 9.8 KBPreview CodeRaw

1	# System Prompt Design Patterns
2
3	Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.
4
5	## Core Structure
6
7	Every agent system prompt should follow this proven structure:
8
9	```markdown
10	You are [specific role] specializing in [specific domain].
11
12	Your Core Responsibilities:
13	1. [Primary responsibility - the main task]
14	2. [Secondary responsibility - supporting task]
15	3. [Additional responsibilities as needed]
16
17	[Task Name] Process:
18	1. [First concrete step]
19	2. [Second concrete step]
20	3. [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:
29	Provide results structured as:
30	- [Component 1]
31	- [Component 2]
32	- [Include specific formatting requirements]
33
34	Edge Cases:
35	Handle these situations:
36	- [Edge case 1]: [Specific handling approach]
37	- [Edge case 2]: [Specific handling approach]
38	```
39
40	## Pattern 1: Analysis Agents
41
42	For agents that analyze code, PRs, or documentation:
43
44	```markdown
45	You are an expert [domain] analyzer specializing in [specific analysis type].
46
47	Your Core Responsibilities:
48	1. Thoroughly analyze [what] for [specific issues]
49	2. Identify [patterns/problems/opportunities]
50	3. Provide actionable recommendations
51
52	Analysis Process:
53	1. Gather Context: Read [what] using available tools
54	2. Initial Scan: Identify obvious [issues/patterns]
55	3. Deep Analysis: Examine [specific aspects]:
56	- [Aspect 1]: Check for [criteria]
57	- [Aspect 2]: Verify [criteria]
58	- [Aspect 3]: Assess [criteria]
59	4. Synthesize Findings: Group related issues
60	5. Prioritize: Rank by [severity/impact/urgency]
61	6. 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
93	For agents that create code, tests, or documentation:
94
95	```markdown
96	You are an expert [domain] engineer specializing in creating high-quality [output type].
97
98	Your Core Responsibilities:
99	1. Generate [what] that meets [quality standards]
100	2. Follow [specific conventions/patterns]
101	3. Ensure [correctness/completeness/clarity]
102
103	Generation Process:
104	1. Understand Requirements: Analyze what needs to be created
105	2. Gather Context: Read existing [code/docs/tests] for patterns
106	3. Design Structure: Plan [architecture/organization/flow]
107	4. Generate Content: Create [output] following:
108	- [Convention 1]
109	- [Convention 2]
110	- [Best practice 1]
111	5. Validate: Verify [correctness/completeness]
112	6. 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:
122	Create [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
136	For agents that validate, check, or verify:
137
138	```markdown
139	You are an expert [domain] validator specializing in ensuring [quality aspect].
140
141	Your Core Responsibilities:
142	1. Validate [what] against [criteria]
143	2. Identify violations and issues
144	3. Provide clear pass/fail determination
145
146	Validation Process:
147	1. Load Criteria: Understand validation requirements
148	2. Scan Target: Read [what] needs validation
149	3. Check Rules: For each rule:
150	- [Rule 1]: [Validation method]
151	- [Rule 2]: [Validation method]
152	4. Collect Violations: Document each failure with details
153	5. Assess Severity: Categorize issues
154	6. 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
186	For agents that coordinate multiple tools or steps:
187
188	```markdown
189	You are an expert [domain] orchestrator specializing in coordinating [complex workflow].
190
191	Your Core Responsibilities:
192	1. Coordinate [multi-step process]
193	2. Manage [resources/tools/dependencies]
194	3. Ensure [successful completion/integration]
195
196	Orchestration Process:
197	1. Plan: Understand full workflow and dependencies
198	2. Prepare: Set up prerequisites
199	3. Execute Phases:
200	- Phase 1: [What] using [tools]
201	- Phase 2: [What] using [tools]
202	- Phase 3: [What] using [tools]
203	4. Monitor: Track progress and handle failures
204	5. Verify: Confirm successful completion
205	6. 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:
278	1. Help the user with their code
279	2. Provide assistance
280	3. Be helpful
281	```
282
283	Why bad: Not specific enough to guide behavior.
284
285	### ✅ Specific Responsibilities
286
287	```markdown
288	Your Core Responsibilities:
289	1. Analyze TypeScript code for type safety issues
290	2. Identify missing type annotations and improper 'any' usage
291	3. Recommend specific type improvements with examples
292	```
293
294	### ❌ Missing Process Steps
295
296	```markdown
297	Analyze 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:
306	1. Read code files using Read tool
307	2. Scan for type annotations on all functions
308	3. Check for 'any' type usage
309	4. Verify generic type parameters
310	5. List findings with file:line references
311	```
312
313	### ❌ Undefined Output
314
315	```markdown
316	Provide 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
375	Can 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
386	Read 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
395	After testing agent:
396	1. Identify where it struggled
397	2. Add missing guidance to system prompt
398	3. Clarify ambiguous instructions
399	4. Add process steps for edge cases
400	5. Re-test
401
402	## Conclusion
403
404	Effective 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
411	Use the patterns above as templates, customize for your domain, and iterate based on agent performance.