dair-ai / dair-ai/Prompt-Engineering-Guide
[Proposal] New Guide: Mechanical Guards for AI Agents
- Dominant language
- MDX
- Stars
- 78.3k
- Forks
- 8.6k
- PR merge metrics
- No merged PRs in 30d
Description
## Proposed Section: Mechanical Guards for AI Agents
A new guide covering a category of prompt engineering currently missing from the guide: **mechanical verification patterns** that compensate for an LLM's structural inability to verify its own NL output.
## The Gap
Current guides cover prompt design, reliability patterns, and adversarial robustness. But there's a distinct category not yet covered: deterministic, filesystem-level checks that **bypass** the LLM's reasoning layer entirely — because the LLM cannot reliably judge its own configuration integrity.
## Core Concept: The Prose Barrier
Any NL-based AI agent shares a structural constraint: its verification loop and generation loop use the same channel. An agent cannot independently verify its own NL output — it can only produce more NL claiming the first NL was correct. This is not a bug — it's an architectural property.
## What the Guide Would Cover
1. **The Prose Barrier** — why AI agents structurally cannot self-verify NL output
2. **Mechanical Gate Patterns** — filesystem checks (mtime, regex, exit codes, hook wiring) that verify config integrity without AI involvement
3. **Dual-Layer Architecture** — process-layer soft monitoring + output-layer hard blocking
4. **Causal Evidence** — config rules causally shape agent behavior (n=30 experiment, p=0.0092)
5. **Implementation Patterns** — SessionStart/PreToolUse/Stop hook designs for mechanical verification
## Evidence
- 50+ session production deployment
- Causal experiment: odds ratio 11.0, p=0.0092
- Independent structural convergence with Anthropic J-space (July 2026)
- ECC 226K★ repo: delivery-gate merged (#2378)
## Scope
~2000 words, fits as a new guide under `guides/prompts-mechanical-guards.md`. Complementary to existing `prompts-reliability.md` — focuses on the verification layer rather than prompt design patterns.
Happy to draft the full guide if maintainers are interested.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with guides/prompts-reliability.md and compare its coverage with the proposed guides/prompts-mechanical-guards.md. Draft the approximately 2,000-word guide covering the Prose Barrier, mechanical gate patterns, dual-layer architecture, causal evidence, and hook designs, with the cited evidence accurately represented.
Written by the indexing model from the issue text.
Assessment
- Domain
- ai, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100