docs(harness-principles): add 3 principles from HumanLayer 12-factor-agents#30
Draft
markhazlett wants to merge 1 commit into
Draft
docs(harness-principles): add 3 principles from HumanLayer 12-factor-agents#30markhazlett wants to merge 1 commit into
markhazlett wants to merge 1 commit into
Conversation
…agents - Typed Event Ledger (Factor 3): active context curation over passive accumulation - Serialization Granularity (Factors 6+8): pause between tool selection and execution - Prompts as Versioned, Testable Code (Factor 2): prompts need evals like code does Also bootstraps the ## Sources mined section (absent until this run) and adds Part XIII for externally-mined principles. Cognition "Don't Build Multi-Agents" and Anthropic "Building Effective Agents" logged in Sources mined as researched; both primary sources returned HTTP 403 so no principles were extracted from them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Mines Dex Horthy's 12-factor-agents (HumanLayer, early 2025) for principles transferable to this harness. Three principles cleared the quality bar and are added as Part XIII — Principles from External Harness Research. This run also bootstraps the
## Sources minedsection, which was absent from the file.Two other harnesses were researched (Cognition "Don't Build Multi-Agents", Anthropic "Building Effective Agents") but their primary sources returned HTTP 403; they are logged in Sources mined without extracted principles.
Principles added
All three sourced from directly-fetched GitHub raw files in the 12-factor-agents repo.
Sources (primary URLs verified)
Principle synopses
§64 Typed Event Ledger — Don't pass raw message arrays to the model. Define a typed event system (
Thread/Event), serialize to custom XML/YAML markup, and actively prune: remove resolved errors, filter sensitive data. Distinct from §5 (which tiers prompt sources); this is about the internal structure of what the model sees within a turn.§65 Serialization Granularity — Most frameworks pause/resume between LLM turns, not between tool selection and tool execution. Without sub-turn serialization, human approval before dangerous tool invocations forces three bad tradeoffs: pause in memory (lose state on restart), restrict to low-risk tools only, or grant broad permissions. This names a structural gap in standard orchestrators.
§66 Prompts as Versioned Code — Framework abstractions that hide prompts get you to 70–80% quality but block further tuning. Prompts in source control are diffable and testable. Evaluations for prompts catch regression the way unit tests catch code regression. Connects to the harness's
/skill-evalwork: treating skill bodies as "prompts with required eval suites" would complete the analogy.Not in scope
This PR only edits
.claude/docs/harness-principles.md. Skills, hooks, agents, commands, and all other files are unchanged. Adoption of any principle as a harness feature is a follow-up task if approved.Generated by Claude Code