Skip to content

docs: add evidence-based agent prompt principles#14

Merged
mpawliszyn merged 1 commit intomainfrom
docs/agent-prompt-principles
Feb 26, 2026
Merged

docs: add evidence-based agent prompt principles#14
mpawliszyn merged 1 commit intomainfrom
docs/agent-prompt-principles

Conversation

@mpawliszyn
Copy link
Copy Markdown
Collaborator

Summary

  • 12 evidence-based principles for writing effective agent prompts in Fowlcon
  • Derived from comprehensive research across cognitive science, LLM behavioral studies, multi-agent orchestration patterns, and production agent tools
  • Will directly guide implementation of agent prompts in Phases 2-4

Key Principles

  1. Agents are tools, not peers -- structured output, no back-and-forth
  2. Format constraints control behavior -- Aider showed 3x improvement
  3. Negative constraints before positive -- the RPI documentarian mandate
  4. Name the rationalizations -- Superpowers red flags table pattern
  5. Mechanical verification over self-assessment -- scripts, not self-reports
  6. One agent, one job -- tool restrictions enforce specialization
  7. Context inline, never file references -- guaranteed visibility
  8. Tree structure limits -- 2-3 levels, 3-5 children/node (cognitive load research)
  9. Unified diff format -- omit hunk line numbers, include context lines
  10. Design for fresh starts -- 39% multi-turn degradation, state on disk
  11. Supervisor mode for parallel agents -- failures as data, not exceptions
  12. The reviewer is the protagonist -- anti-automation-bias design

Research backing

Backed by 16 research documents (6,800+ lines) covering multi-agent patterns, cognitive science, production tools, and benchmarks. Full research library in the private design repo.

Test plan

  • Read through all 12 principles for clarity and correctness
  • Verify research citations match source material
  • Confirm principles align with existing AGENTS.md conventions
  • Check for conflicts with the 10 core principles in README.md

🤖 Generated with Claude Code

12 principles for writing effective agent prompts, derived from research
on multi-agent orchestration, cognitive science, LLM behavioral studies,
and production agent tools. Covers:

- Agent-as-tool over agent-as-peer (Anthropic recommendation)
- Format constraints as behavioral control (Aider: 3x improvement)
- Negative constraints before positive instructions (RPI pattern)
- Named anti-rationalization tables (Superpowers pattern)
- Mechanical verification over self-assessment
- Cognitive load limits for tree structure (Miller/Cowan research)
- Unified diff format for agent consumption (Diff-XYZ benchmark)
- Fresh start design for long sessions (39% multi-turn degradation)
- Supervisor mode for parallel agents
- The reviewer as protagonist (anti-automation-bias)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@mpawliszyn mpawliszyn merged commit 7d3f073 into main Feb 26, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant