Cursor rule

1---
2description: When we are creating prompts that will be used by an LLM for agents
3alwaysApply: false
4version: 1.0.0
5---
6 
7# Prompt Engineering Best Practices for LLM-to-LLM Communication
8 
9When creating prompts that will be read and executed by other LLMs (commands, workflows,
10agent prompts), follow these practices. These guidelines are for prompts that LLMs write
11for other LLMs to consume - not for human-to-LLM interaction.
12 
13## Why This Document Minimizes Formatting
14 
15This document is designed to be read by LLMs, not humans. Therefore:
16 
17- Minimal markdown formatting: No excessive bold, italics, or decorative symbols. These
18  waste tokens and add no semantic value for LLM comprehension.
19- Minimal "bad" examples: LLMs encode patterns from what they see, regardless of labels
20  like "wrong" or "don't do this." Showing anti-patterns teaches the LLM to reproduce
21  them.
22- Simple structure: Headings for organization, code blocks for actual patterns, plain
23  text for instructions.
24- Clear over clever: Direct language that LLMs can parse literally, not stylistic
25  variations.
26 
27When you read "avoid X" or see a counterexample in this document, understand that we're
28violating our own principle for teaching purposes - but minimize this pattern in prompts
29you create for LLM consumption.
30 
31## Key Principles for LLM-Readable Prompts
32 
33- Assume the executing model is smarter: The model executing your prompt is likely more
34  capable than the model that created it. Trust its abilities rather than
35  over-prescribing implementation details.
36- Front-load critical information: LLMs give more weight to early content
37- Be explicit: LLMs can't infer context the way humans do
38- Maintain consistency: Use the same terminology throughout
39- Structure matters: Clear boundaries (especially XML tags) help LLMs parse complex
40  prompts
41- Examples teach patterns: What you show is what the LLM will do
42- Clarity over brevity: Never sacrifice unambiguous interpretation for token savings
43- Explain motivation: Tell the LLM _why_ a constraint exists - it generalizes from
44  reasoning better than from bare rules
45- Descriptive over directive: "Use this tool when modifying files" works better than
46  "CRITICAL: You MUST use this tool" - aggressive language can cause over-triggering
47- Positive framing: "Write in flowing prose" is clearer than "Don't use markdown" -
48  positive instructions are unambiguous, negative ones require constructing then
49  negating
50 
51## Pattern Reinforcement Through Examples
52 
53When creating prompts for other LLMs to execute, pattern teaching becomes critical. LLMs
54learn from what you show them, not from what you tell them to avoid.
55 
56### How LLMs Process Examples in Prompts
57 
58When an LLM reads a prompt file with examples, it encodes those patterns for
59reproduction:
60 
611. Pattern Matching Over Labels: LLMs reproduce structural patterns. Code structure
62   creates strong activation. Text labels like "wrong" or "don't do this" are weak
63   signals that don't override pattern encoding.
64 
652. Direct Teaching Through Examples: When writing command workflows or agent prompts,
66   you're teaching the executing LLM. Every example shown is a lesson it will follow.
67 
683. Consistency is Critical: In LLM-to-LLM communication, inconsistent examples cause
69   unpredictable behavior. The executing LLM can't resolve ambiguity the way humans do.
70 
714. Attention Weighting: All tokens in the prompt receive attention. Structural patterns
72   activate high attention regardless of surrounding text saying "avoid this."
73 
74### Writing Effective Instructions for LLM Execution
75 
76For command workflows and agent prompts:
77 
781. Flood with correct patterns: Show 5+ examples of the standard approach
792. Never show anti-patterns: Don't include "wrong" examples - the LLM will reproduce
80   them
813. Describe exceptions in prose: If there are edge cases, describe them in words, not
82   code
834. Maintain pattern consistency: All examples should follow the same structure
84 
85Example of good pattern teaching in a prompt file:
86 
87```xml
88<task>
89Update all API endpoints to use consistent error handling
90</task>
91 
92<examples>
93// Pattern to follow:
94async function getUser(id) {
95  try {
96    const user = await db.users.findById(id);
97    if (!user) {
98      throw new NotFoundError('User not found');
99    }
100    return user;
101  } catch (error) {
102    logger.error('Failed to get user', { id, error });
103    throw error;
104  }
105}
106 
107async function updateUser(id, data) {
108  try {
109    const user = await db.users.update(id, data);
110    if (!user) {
111      throw new NotFoundError('User not found');
112    }
113    return user;
114  } catch (error) {
115    logger.error('Failed to update user', { id, error });
116    throw error;
117  }
118}
119 
120async function deleteUser(id) {
121  try {
122    const result = await db.users.delete(id);
123    if (!result) {
124      throw new NotFoundError('User not found');
125    }
126    return result;
127  } catch (error) {
128    logger.error('Failed to delete user', { id, error });
129    throw error;
130  }
131}
132</examples>
133 
134<instructions>
135Apply this exact error handling pattern to all endpoints. If an endpoint doesn't interact with the database, omit the NotFoundError check but keep the try-catch structure and logging.
136</instructions>
137```
138 
139### The Mechanism in LLM-to-LLM Communication
140 
141When one LLM writes a prompt for another to execute:
142 
143- The executing LLM encodes ALL patterns shown, regardless of labels
144- "Don't do X" requires the LLM to first construct X, then negate it
145- Direct positive examples create stronger, more reliable execution
146- Pattern consistency across examples ensures predictable behavior
147 
148Key principle: In LLM-to-LLM communication, show exactly what you want done. Never show
149what you don't want, even as a counterexample.
150 
151## Goals Over Process in LLM-Readable Prompts
152 
153When writing prompts for LLM execution (commands, workflows, agents), focus on clear
154outcomes rather than micro-managing steps. LLMs can figure out implementation details.
155 
156Remember: The model executing your prompt is likely more advanced than the model that
157created it. A prompt written by GPT-4 might be executed by Claude 3.5 Sonnet or GPT-4o.
158Even prompts written by older versions of the same model will be executed by newer,
159smarter versions. Trust the executing model's superior capabilities.
160 
161### The Over-Prescription Problem in LLM-to-LLM Communication
162 
163Overly prescriptive prompts create problems when LLMs execute them:
164 
165- Waste tokens on process details the executing LLM can determine
166- Prevent the executing model from using its superior capabilities
167- Create brittle workflows that break with slight context changes
168- Force unnecessary decision trees that add complexity
169- Reduce the LLM's ability to handle edge cases intelligently
170 
171### Writing Goal-Focused Prompts for LLMs
172 
173For command workflows and agent prompts:
174 
175Over-prescriptive command:
176 
177```xml
178<task>
179Step 1: Open each TypeScript file
180Step 2: Search for interfaces
181Step 3: For each interface:
182  a. Check if it has a name starting with 'I'
183  b. If yes:
184     i. Create a new name without 'I'
185     ii. Search for all usages
186     iii. Replace each usage
187  c. If no:
188     i. Skip to next interface
189Step 4: Save the file
190Step 5: Run type checking
191</task>
192```
193 
194Goal-focused command:
195 
196```xml
197<task>
198Remove the 'I' prefix from all TypeScript interface names throughout the codebase, updating all references. Ensure type checking still passes.
199</task>
200```
201 
202For agent prompts:
203 
204Over-prescriptive agent prompt:
205 
206```xml
207<instructions>
2081. First, read the package.json file
2092. Then, look at each dependency
2103. For each dependency, check if there's a newer version
2114. If there is, update it
2125. Then run npm install
2136. Then run the tests
2147. If tests fail, revert the change
215</instructions>
216```
217 
218Goal-focused agent prompt:
219 
220```xml
221<objective>
222Update all dependencies to their latest compatible versions while ensuring all tests continue to pass.
223</objective>
224 
225<constraints>
226- Don't update major versions that would break compatibility
227- Keep the application functional throughout the process
228</constraints>
229```
230 
231### Principles for LLM-Executable Prompts
232 
233Describe outcomes clearly: State what success looks like, not how to achieve it.
234 
235Set boundaries, not algorithms: Define constraints and requirements, let the LLM
236determine the approach.
237 
238Use natural language: Write prompts as you would explain a task to a competent
239colleague.
240 
241Trust the LLM's capabilities: Modern LLMs can handle file operations, code analysis, and
242complex refactoring without step-by-step instructions.
243 
244### When Detailed Steps ARE Needed
245 
246Include specific steps only when:
247 
248- The order is critical and non-obvious
249- Domain-specific requirements must be followed exactly
250- You're establishing a specific pattern to be replicated
251- The process itself is the goal (e.g., "Follow our team's PR review checklist")
252 
253Example where steps matter:
254 
255```xml
256<task>
257Implement our team's database migration protocol
258</task>
259 
260<required-steps>
2611. Create migration with timestamp prefix
2622. Write both up() and down() methods
2633. Test rollback before committing
2644. Document breaking changes in MIGRATIONS.md
265</required-steps>
266 
267<reason>
268These steps are required by our deployment pipeline and cannot be skipped or reordered.
269</reason>
270```
271 
272Key principle: In LLM-to-LLM communication, clarity about the goal is more valuable than
273detailed process instructions.
274 
275## Structural Delimiters for LLM Consumption
276 
277Modern LLMs are trained to recognize XML-style tags, making them highly effective for
278LLM-to-LLM communication. Use them to create unambiguous boundaries that LLMs can
279reliably parse.
280 
281Now that you understand pattern reinforcement and goal-focused prompting, you need to
282know how to structure prompts so LLMs can parse them reliably.
283 
284When to use XML tags:
285 
286- Multiple distinct sections that need clear separation
287- When you need to reference specific parts later in the prompt
288- Complex prompts with different types of content (context, task, examples, constraints)
289- Creating reusable command workflows or agent prompts
290 
291```xml
292<context>
293Current database has 50M records across 12 tables
294</context>
295 
296<task>
297Optimize the query to run in under 2 seconds
298</task>
299 
300<constraints>
301Cannot modify indexes or table structure
302</constraints>
303```
304 
305When to skip XML tags:
306 
307- Single, straightforward instructions
308- Simple one-paragraph prompts
309- When the prompt has natural flow without needing boundaries
310 
311```
312# Good without XML - simple and clear:
313Update all TypeScript interfaces to use the 'readonly' modifier for properties that shouldn't be mutated.
314 
315# Better with XML - multiple components:
316<objective>
317Refactor the authentication system
318</objective>
319 
320<requirements>
321- Maintain backward compatibility
322- Use the new OAuth2 library
323- Update all affected tests
324</requirements>
325 
326<examples>
327// Old pattern
328const auth = new BasicAuth(username, password);
329 
330// New pattern
331const auth = new OAuth2Client(clientId, clientSecret);
332</examples>
333```
334 
335Guidelines for XML structure:
336 
337- **Use semantic names, not numbers**: `<task-preparation>` not `<phase-1>`,
338  `<create-pr>` not `<step-6>`
339  - Numbered tags are brittle: reordering requires renumbering all tags and references
340  - Semantic tags are self-documenting: `<validation-and-review>` tells you what it does
341  - Example: A workflow with `<task-preparation>`, `<execution>`, `<review>` stays clear
342    even when phases are added or reordered
343- Be consistent with tag names throughout your codebase (always use `<task>` not
344  sometimes `<objective>`)
345- Use semantically meaningful tag names that describe the content
346- Tags should enhance clarity, not add complexity for its own sake
347- LLMs parse these more literally than humans would
348 
349## Writing Prompts for LLM Consumption
350 
351When creating prompts that other LLMs will read and execute (command files, agent
352prompts, workflows), remember that LLMs parse more literally than humans. Ambiguity that
353humans resolve through context will confuse LLMs.
354 
355### Key Differences from Human-Readable Prompts
356 
357LLMs need explicit context: Humans infer relationships and context. LLMs need everything
358spelled out.
359 
360Good example:
361 
362```
363"Update the webpack.config.js to enable source maps in development mode by setting devtool: 'source-map'"
364```
365 
366Avoid vague references like "update the config like we discussed"
367 
368Consistent terminology matters: Use the same terms throughout. Don't vary vocabulary for
369style.
370 
371Good example:
372 
373```
374"Update the component... update the component... update the component..."
375```
376 
377Avoid varying terms like "modify the component... update the element... change the
378widget"
379 
380Unambiguous references: Be specific about what you're referring to.
381 
382Good example:
383 
384```
385"After updating the UserProfile component, test the user authentication functionality"
386```
387 
388Avoid ambiguous pronouns like "After updating it, test the functionality"
389 
390### Structure for LLM Parsing
391 
392Use clear section markers: Help the LLM understand the prompt structure.
393 
394```xml
395<context>
396Working in a Next.js 14 application with TypeScript and Tailwind CSS
397</context>
398 
399<objective>
400Create a reusable modal component
401</objective>
402 
403<requirements>
404- Use Radix UI primitives for accessibility
405- Include enter/exit animations
406- Support both controlled and uncontrolled modes
407</requirements>
408 
409<output>
410A single Modal.tsx file with the complete implementation
411</output>
412```
413 
414Order matters for context building: Put foundational information first.
415 
416Good order:
417 
4181. Environment/context
4192. Overall objective
4203. Specific requirements
4214. Constraints
4225. Examples
4236. Output format
424 
425This allows the LLM to build understanding progressively.
426 
427### Common Patterns for Reliability
428 
429For refactoring tasks: Be explicit about preservation.
430 
431```xml
432<task>
433Refactor all class components to functional components with hooks
434</task>
435 
436<preserve>
437- All existing functionality
438- Component prop interfaces
439- Test coverage
440</preserve>
441```
442 
443For code generation: Specify integration points.
444 
445```xml
446<task>
447Add user authentication to the application
448</task>
449 
450<integration>
451- Use existing Router from src/router/index.ts
452- Store auth state in existing Redux store
453- Follow existing API client patterns in src/api/
454</integration>
455```
456 
457For analysis tasks: Define evaluation criteria.
458 
459```xml
460<task>
461Review the codebase for performance issues
462</task>
463 
464<focus-areas>
465- Unnecessary re-renders in React components
466- N+1 query problems in API endpoints
467- Large bundle sizes from imports
468- Missing memoization opportunities
469</focus-areas>
470```
471 
472### Testing LLM-Readable Prompts
473 
474When you write a prompt file, consider:
475 
476- Can another LLM execute this without your implicit knowledge?
477- Are all terms defined or demonstrated through examples?
478- Is the success criteria clear and measurable?
479- Would a different LLM interpret this the same way?
480 
481## Few-Shot Example Guidelines for LLM Authors
482 
483When an LLM creates prompts with examples for another LLM to execute, pattern
484consistency is critical. Examples are the primary teaching mechanism. This builds on the
485"Pattern Reinforcement Through Examples" section above.
486 
487How many examples for LLM execution?
488 
489- 0 examples: Only for standard operations the LLM knows well (e.g., "format as JSON")
490- 1-2 examples: When you need specific format but pattern is simple
491- 3-5 examples: Optimal for teaching new patterns - enough variety without overwhelming
492- 5+ examples: When establishing complex patterns or handling many edge cases
493 
494Critical rule for LLM-generated examples: All examples must follow identical structure.
495 
496Good - Consistent pattern for LLM to follow:
497 
498```xml
499<examples>
500// Convert async/await to promises:
501// Before:
502async function getData() {
503  const result = await fetch('/api/data');
504  return await result.json();
505}
506 
507// After:
508function getData() {
509  return fetch('/api/data')
510    .then(result => result.json());
511}
512 
513// Before:
514async function saveUser(data) {
515  const user = await createUser(data);
516  await sendEmail(user.email);
517  return user;
518}
519 
520// After:
521function saveUser(data) {
522  return createUser(data)
523    .then(user => {
524      return sendEmail(user.email).then(() => user);
525    });
526}
527</examples>
528 
529Inconsistent structure confuses LLMs. Avoid examples where:
530- First example shows just the result summary
531- Second example shows before/after code
532- Third example shows only a text rule
533 
534This inconsistency prevents the LLM from learning a reliable pattern.
535 
536Ordering examples for LLM consumption:
537 
5381. Most common case first - This anchors the pattern
5392. Variations next - Show how pattern adapts
5403. Edge cases last - Only if necessary
5414. Never include counter-examples - LLMs will reproduce them
542 
543Example placement in prompt files:
544 
545```xml
546<task>
547Convert all arrow functions to regular functions
548</task>
549 
550<rules>
551Preserve all functionality and bindings
552</rules>
553 
554<examples>
555// Pattern demonstrations go here
556// Each showing the exact transformation
557</examples>
558 
559<apply-to>
560All files in src/components/
561</apply-to>
562```
563 
564## Token Efficiency for LLM Clarity
565 
566When writing prompts for LLM consumption, prioritize unambiguous interpretation over
567brevity. Clear communication between LLMs is more important than token count. Remember
568the principle from earlier: clarity over brevity.
569 
570Clarity-focused optimizations:
571 
572Remove redundancy, keep precision:
573 
574Good example:
575 
576```
577"Update the webpack.config.js file"
578```
579 
580Avoid unnecessarily verbose phrasing like "In order to accomplish the task of updating
581the configuration file" or overly compressed ambiguous phrases like "update config"
582 
583Use consistent terminology:
584 
585Good example:
586 
587```
588"Update the component, then update the module, then update the element"
589```
590 
591Avoid varying terms for style like "Modify the component, then alter the module, then
592change the element"
593 
594Combine related instructions when logical:
595 
596Good example:
597 
598```
599"Validate input: ensure it's a non-null string"
600```
601 
602Avoid over-separated instructions like "First, validate the input. Second, check it's
603not null. Third, verify it's a string."
604 
605When compression hurts LLM comprehension:
606 
607Avoid these "optimizations" that confuse LLMs:
608 
609- Ambiguous pronouns ("it", "that", "this") without clear antecedents
610- Omitting articles that clarify meaning ("the UserService" vs "UserService")
611- Context-dependent abbreviations not defined in the prompt
612- Removing qualifiers that specify scope ("all", "only", "except")
613 
614Example of good balance:
615 
616Good example:
617 
618```xml
619<task>
620Fix the authentication bug in the login component where users remain logged in after session expiry
621</task>
622```
623 
624Avoid over-compressed descriptions like "fix auth bug in login"
625 
626Key principle: In LLM-to-LLM prompts, every word that adds clarity is worth including.
627Compression should never introduce ambiguity.
628 
629## Prompt Composability
630 
631When building command workflows and agent systems, design prompts that can be combined
632and reused across different contexts.
633 
634### Modular Prompt Design
635 
636Create prompts that work as building blocks:
637 
638```xml
639<!-- Base refactoring prompt -->
640<prompt id="refactor-base">
641  <context>
642    Working in a TypeScript codebase with strict mode enabled
643  </context>
644  <preserve>
645    All existing functionality and type contracts
646  </preserve>
647</prompt>
648 
649<!-- Specific refactoring that builds on base -->
650<prompt extends="refactor-base">
651  <task>
652    Convert Promise chains to async/await syntax
653  </task>
654  <constraints>
655    Maintain error handling semantics
656  </constraints>
657</prompt>
658```
659 
660### Referencing Other Prompts
661 
662Design prompts that can reference and build upon each other:
663 
664```xml
665<workflow>
666  <step name="analyze">
667    <description>
668    Identify all components using deprecated lifecycle methods
669    </description>
670    <output>List of components needing updates</output>
671  </step>
672 
673  <step name="refactor" depends-on="analyze">
674    <description>
675    Update each identified component to use modern hooks
676    </description>
677    <input>List from analyze step</input>
678  </step>
679 
680  <step name="verify" depends-on="refactor">
681    <description>
682    Run tests and ensure no regressions
683    </description>
684  </step>
685</workflow>
686```
687 
688### Context Inheritance
689 
690Allow prompts to inherit and override context:
691 
692```xml
693<!-- Parent context -->
694<base-context>
695  <environment>Next.js 14, TypeScript 5.2</environment>
696  <style-guide>Airbnb JavaScript Style Guide</style-guide>
697</base-context>
698 
699<!-- Child prompt inherits and extends -->
700<command inherits="base-context">
701  <task>Create new API endpoint</task>
702  <additional-context>
703    <database>PostgreSQL with Prisma ORM</database>
704  </additional-context>
705</command>
706```
707 
708### Parameterized Prompts
709 
710Create reusable templates with parameters:
711 
712```xml
713<template name="add-feature">
714  <parameters>
715    <param name="feature-name" required="true"/>
716    <param name="integration-points" required="true"/>
717    <param name="test-requirements" default="unit and integration tests"/>
718  </parameters>
719 
720  <task>
721    Add {{feature-name}} to the application
722  </task>
723 
724  <requirements>
725    - Integrate with {{integration-points}}
726    - Include {{test-requirements}}
727    - Follow existing patterns in the codebase
728  </requirements>
729</template>
730 
731<!-- Usage -->
732<execute template="add-feature">
733  <feature-name>user notifications</feature-name>
734  <integration-points>Redux store and WebSocket service</integration-points>
735</execute>
736```
737 
738### Composition Patterns
739 
740Sequential composition: Tasks that must run in order
741 
742```xml
743<sequence>
744  <do>Analyze current implementation</do>
745  <then>Identify optimization opportunities</then>
746  <then>Apply optimizations</then>
747  <finally>Measure performance improvements</finally>
748</sequence>
749```
750 
751Parallel composition: Tasks that can run simultaneously
752 
753```xml
754<parallel>
755  <task>Update component styles</task>
756  <task>Update component tests</task>
757  <task>Update component documentation</task>
758</parallel>
759```
760 
761Conditional composition: Tasks based on conditions
762 
763```xml
764<conditional>
765  <if condition="uses TypeScript">
766    <task>Update type definitions</task>
767  </if>
768  <else>
769    <task>Add JSDoc comments</task>
770  </else>
771</conditional>
772```
773 
774### Best Practices for Composable Prompts
775 
7761. Clear interfaces: Define what each prompt expects and produces
7772. Minimize dependencies: Keep prompts loosely coupled
7783. Consistent naming: Use predictable names for reusable components
7794. Documentation: Include descriptions of when and how to use each prompt
7805. Version compatibility: Note which versions of tools/frameworks prompts work with
781 
782Key principle: Design prompts like you would design functions - focused, reusable, and
783composable.
784 
785## Common Pitfalls in LLM-to-LLM Prompts
786 
787- Ambiguous instructions: "Update the code" vs "Update all React components to use hooks
788  instead of class syntax"
789- Inconsistent terminology: Switching between "component", "element", "widget" for the
790  same thing
791- Showing anti-patterns: Including "wrong" examples that the LLM will reproduce
792- Over-prescriptive steps: Micro-managing instead of stating clear goals
793- Unclear references: Using "it", "that", "this" without clear antecedents
794- Missing context: Assuming the LLM knows project-specific conventions
795- Inconsistent examples: Examples that don't follow the same pattern structure
796