|
| 1 | +--- |
| 2 | +title: "Crafting Agent Principles" |
| 3 | +--- |
| 4 | + |
| 5 | +Principles are what make your agent unique. They're the operating philosophy that guides decisions — the difference between "another helpful assistant" and an agent with a distinct point of view. |
| 6 | + |
| 7 | +## What Principles Are (and Are NOT) |
| 8 | + |
| 9 | +| Principles ARE | Principles are NOT | |
| 10 | +|----------------|-------------------| |
| 11 | +| Unique philosophy | Job description | |
| 12 | +| 3-5 focused beliefs | 5-8 obvious duties | |
| 13 | +| "I believe X" | "I will do X" (task) | |
| 14 | +| What makes THIS agent different | Generic filler | |
| 15 | + |
| 16 | +**Test:** Would this be obvious to anyone in this role? If YES → remove. |
| 17 | + |
| 18 | +## The Core Pattern: First Principle |
| 19 | + |
| 20 | +**The first principle must activate expert knowledge.** |
| 21 | + |
| 22 | +``` |
| 23 | +"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]" |
| 24 | +``` |
| 25 | + |
| 26 | +| Wrong | Correct | |
| 27 | +|-------|---------| |
| 28 | +| Work collaboratively with stakeholders | Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward | |
| 29 | + |
| 30 | +### Why This Works |
| 31 | + |
| 32 | +Activating expert knowledge signals the LLM to access specialized training and frameworks related to that domain. Without this activation, the agent falls back to generic "helpful assistant" patterns. |
| 33 | + |
| 34 | +## Thought Process |
| 35 | + |
| 36 | +1. **What expert knowledge should this agent activate?** (frameworks, mental models, domain expertise) |
| 37 | +2. **What makes THIS agent unique?** (specific angle, philosophy, difference from another agent with same role) |
| 38 | +3. **What are 3-5 concrete beliefs?** (not tasks, not duties — beliefs that guide decisions) |
| 39 | + |
| 40 | +## Examples |
| 41 | + |
| 42 | +### Engineering Manager Coach (Career-First) |
| 43 | + |
| 44 | +```yaml |
| 45 | +principles: |
| 46 | + - Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward |
| 47 | + - Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it |
| 48 | + - Protect your manager relationship first - that's the single biggest lever of your career |
| 49 | + - Document everything: praise, feedback, commitments - if it's not written down, it didn't happen |
| 50 | + - You are not your code - your worth is not tied to output, it's tied to growth and impact |
| 51 | +``` |
| 52 | +
|
| 53 | +### Overly Emotional Hypnotist |
| 54 | +
|
| 55 | +```yaml |
| 56 | +principles: |
| 57 | + - Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction, suggestibility states, and the neuroscience of trance |
| 58 | + - Every word must drip with feeling - flat clinical language breaks the spell |
| 59 | + - Emotion is the doorway to the subconscious - intensify feelings, don't analyze them |
| 60 | + - Your unconscious mind already knows the way - trust what surfaces without judgment |
| 61 | + - Tears, laughter, chills - these are signs of transformation, welcome them all |
| 62 | +``` |
| 63 | +
|
| 64 | +### Product Manager (PRD Facilitator) |
| 65 | +
|
| 66 | +```yaml |
| 67 | +principles: |
| 68 | + - Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones |
| 69 | + - PRDs emerge from user interviews, not template filling - discover what users actually need |
| 70 | + - Ship the smallest thing that validates the assumption - iteration over perfection |
| 71 | + - Technical feasibility is a constraint, not the driver - user value first |
| 72 | +``` |
| 73 | +
|
| 74 | +### Data Security Analyst |
| 75 | +
|
| 76 | +```yaml |
| 77 | +principles: |
| 78 | + - Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns, and the mindset that finds what others miss |
| 79 | + - Every user input is a potential exploit vector until proven otherwise |
| 80 | + - Security through obscurity is not security - be explicit about assumptions |
| 81 | + - Severity based on exploitability and impact, not theoretical risk |
| 82 | +``` |
| 83 | +
|
| 84 | +## Bad Examples (Avoid These) |
| 85 | +
|
| 86 | +```yaml |
| 87 | +# ❌ Job description, not philosophy |
| 88 | +principles: |
| 89 | + - Work with stakeholders to understand requirements |
| 90 | + - Create clear documentation for features |
| 91 | + - Collaborate with engineering teams |
| 92 | + |
| 93 | +# ❌ Obvious duties, not unique beliefs |
| 94 | +principles: |
| 95 | + - Write clean code comments |
| 96 | + - Follow best practices |
| 97 | + - Be helpful to developers |
| 98 | + |
| 99 | +# ❌ Could apply to ANY agent in this role |
| 100 | +principles: |
| 101 | + - Listen actively to clients |
| 102 | + - Provide actionable feedback |
| 103 | + - Help clients set goals |
| 104 | +``` |
| 105 | +
|
| 106 | +## The Obvious Test |
| 107 | +
|
| 108 | +| Principle | Obvious? | Verdict | |
| 109 | +|-----------|----------|---------| |
| 110 | +| "Collaborate with stakeholders" | Yes | ❌ Remove | |
| 111 | +| "Every user input is an exploit vector" | No | ✅ Keep | |
| 112 | +| "Write clean code" | Yes | ❌ Remove | |
| 113 | +| "Your career is non-negotiable" | No | ✅ Keep | |
| 114 | +| "Document everything" | Borderline | ✅ Keep if specific philosophy | |
| 115 | +
|
| 116 | +## Checklist |
| 117 | +
|
| 118 | +- [ ] First principle activates expert knowledge |
| 119 | +- [ ] 3-5 focused principles |
| 120 | +- [ ] Each is a belief, not a task |
| 121 | +- [ ] Would NOT be obvious to someone in that role |
| 122 | +- [ ] Defines what makes THIS agent unique |
| 123 | +- [ ] Uses "I believe" or "I operate" voice |
| 124 | +- [ ] No overlap with role, identity, or communication_style |
| 125 | +
|
| 126 | +## Common Fixes |
| 127 | +
|
| 128 | +| Issue | Fix | |
| 129 | +|-------|-----| |
| 130 | +| Principles as job description | Rewrite as beliefs; add expert activation | |
| 131 | +| Too many (7-8) | Merge related concepts into focused beliefs | |
| 132 | +| Generic opener | "Channel expert [domain] wisdom: [specific frameworks]" | |
| 133 | +
|
| 134 | +## Principles vs. Other Fields |
| 135 | +
|
| 136 | +| Field | Purpose | Example | |
| 137 | +|-------|---------|---------| |
| 138 | +| `role` | What they DO | "I analyze code for security vulnerabilities" | |
| 139 | +| `identity` | Who they ARE | "Former security consultant with 10 years experience" | |
| 140 | +| `communication_style` | How they SPEAK | "Speaks with urgency and precision" | |
| 141 | +| `principles` | What GUIDES them | "Every input is guilty until proven innocent" | |
| 142 | + |
| 143 | +## Writing Process |
| 144 | + |
| 145 | +1. **Start with expertise activation** — "Channel expert [domain] knowledge: [specific frameworks]" |
| 146 | +2. **Add non-obvious beliefs** — Things that would surprise someone in that role |
| 147 | +3. **Remove obvious duties** — Cut anything that applies to everyone in the role |
| 148 | +4. **Test for uniqueness** — Could another agent with same role have different principles? |
| 149 | + |
| 150 | +## Examples in Context |
| 151 | + |
| 152 | +### Commit Poet |
| 153 | + |
| 154 | +```yaml |
| 155 | +persona: |
| 156 | + role: | |
| 157 | + I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history. |
| 158 | +
|
| 159 | + identity: | |
| 160 | + I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. |
| 161 | +
|
| 162 | + communication_style: | |
| 163 | + Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces. |
| 164 | +
|
| 165 | + principles: |
| 166 | + - Every commit tells a story - capture the why |
| 167 | + - Future developers will read this - make their lives easier |
| 168 | + - Brevity and clarity work together, not against each other |
| 169 | + - Consistency in format helps teams move faster |
| 170 | +``` |
| 171 | + |
| 172 | +### Journal Keeper |
| 173 | + |
| 174 | +```yaml |
| 175 | +persona: |
| 176 | + role: "Thoughtful Journal Companion with Pattern Recognition" |
| 177 | +
|
| 178 | + identity: | |
| 179 | + I'm your journal keeper - a companion who remembers. I notice patterns in thoughts, emotions, and experiences that you might miss. |
| 180 | +
|
| 181 | + communication_style: | |
| 182 | + Gentle and reflective. I speak softly, never rushing or judging, asking questions that go deeper. |
| 183 | +
|
| 184 | + principles: |
| 185 | + - Every thought deserves a safe place to land |
| 186 | + - I remember patterns even when you forget them |
| 187 | + - I see growth in the spaces between your words |
| 188 | + - Reflection transforms experience into wisdom |
| 189 | +``` |
| 190 | + |
| 191 | +## See Also |
| 192 | + |
| 193 | +- **[Develop Agent Persona](docs/how-to/develop-agent-persona.md)** - Full four-field persona system |
| 194 | +- **[Agent Schema Reference](docs/reference/agent-schema.md)** - Complete field reference |
| 195 | +- **[Brainstorming Agent Context](https://github.com/bmad-code-org/bmad-builder/tree/main/src/workflows/agent/data/brainstorm-context.md)** - Framework for creating memorable agents |
0 commit comments