Agent Context

Instructions and durable project facts loaded for an agent's current task.

45 items in this guidance cluster.

Tagged guidance

GuideAgent WorkflowToolingVerificationCoding Agentscoding-agentsCoding-agent guidance covers task setup, repo-owned context, tools, workspaces, verification, handoff proof, feedback loops, and maintainer review flow. It treats agents as workers in a system whose output should be reviewable, durable, and easy to integrate.

RuleAgent WorkflowBoundary CorrectnessReview HandoffGive Objectives With BoundariesAGENT-GIVE-OBJECTIVES-WITH-BOUNDARIESDescribe the outcome, scope, non-goals, forbidden moves, and proof instead of handing over brittle steps. Boundaries preserve intent while leaving room for local implementation choices.RuleAgent WorkflowSource TruthDocumentationKeep Durable Context on DiskAGENT-KEEP-DURABLE-CONTEXT-ON-DISKStore project facts, accepted decisions, and long-lived operating notes in files instead of relying on chat context. Durable context makes future sessions and reviews resumable.RuleAgent WorkflowSecurity PrivacyKeep Secrets Out of ContextAGENT-KEEP-SECRETS-OUT-OF-CONTEXTAvoid putting real credentials or sensitive values into prompts, docs, logs, and tests. Keeping secrets out of context reduces leakage through retained, repeated, or committed text.RuleAgent WorkflowReviewabilityPreserve IntentAGENT-PRESERVE-INTENTOptimize for the users underlying objective when literal wording would miss the point. Intent-preserving work keeps changes aligned with the real readability, review, or behavior goal.RuleAgent WorkflowReviewabilityChange ShapeSeparate Notes From CorrectionsAGENT-SEPARATE-NOTES-FROM-CORRECTIONSCapture fast-review notes before fixing them when there are multiple comments or unclear patterns. Separating capture from correction preserves signal and supports coherent follow-up.RuleAgent WorkflowReviewabilityPublic APISpend Human Attention on AmbiguityAGENT-SPEND-HUMAN-ATTENTION-ON-AMBIGUITYAsk for human judgment where product behavior, API compatibility, naming, or security posture is still ambiguous. Resolving direction early prevents large speculative diffs.RuleAgent WorkflowLocal ConventionsSource TruthSuggest Local Override FilesAGENT-SUGGEST-LOCAL-OVERRIDE-FILESPut checkout-only facts in ignored override files instead of shared guidance. Local overrides keep machine-specific steering useful without leaking it to every contributor.RuleAgent WorkflowDocumentationSource TruthUse AGENTS.md as MapAGENT-USE-AGENTS-MD-AS-MAPKeep AGENTS.md compact by using it to route agents to deeper guides and mechanisms. Treating it as a map preserves startup context without losing durable project guidance.

RuleBoundary CorrectnessState TransitionsVerificationDefine Compaction InvariantsBOUNDARY-DEFINE-COMPACTION-INVARIANTSState the budget and cut-point rules before deleting, summarizing, or moving context. Explicit invariants make compaction reviewable and reduce the risk that later work treats lossy or nondeterministic summaries as authoritative.

RuleDocumentationReader LocalityFront-Load Useful PointDOCS-FRONT-LOAD-USEFUL-POINTPut the decision, command, invariant, or warning before broad setup. Readers and agents can then use the page without hunting through introductory prose.RuleDocumentationReader LocalityWrite for Non-Linear ReadersDOCS-WRITE-FOR-NON-LINEAR-READERSGive sections enough local context to work when reached from search, links, review, or retrieval. Avoid repeating the whole introduction; add only the subject and prerequisite needed.

RuleReviewabilityReview HandoffAnswer Questions Before CodeREVIEW-ANSWER-QUESTIONS-BEFORE-CODEAnswer reviewer questions before or alongside the code changes that address them. This keeps intent, tradeoffs, and unresolved choices visible instead of burying the reasoning in a new patch.RuleReviewabilityReview HandoffLet Reviewers Resolve ThreadsREVIEW-LET-REVIEWERS-RESOLVE-THREADSLeave nontrivial review threads for the reviewer to resolve after they confirm the concern was addressed. Authors should only close unambiguous mechanical threads, because resolution carries communication ownership.

RuleSource TruthDocumentationReview HandoffMake Shared Artifacts StandaloneSOURCE-MAKE-SHARED-ARTIFACTS-STANDALONERestate the problem, rationale, evidence, and tradeoffs in shared docs, templates, generated packs, or reusable guidance. Future readers should not need private notes or transcripts to trust the artifact.

PatternAgent WorkflowReviewabilityDocumentationAsk What Were You Trying To Achieveask-what-were-you-trying-to-achieveRecover the original intent before judging a surprising design. Separating purpose from mechanism makes it easier to preserve useful constraints while replacing stale structure.PatternSecurity PrivacyObservabilityAvoid Secret Or Private Log Contextavoid-secret-or-private-log-contextDiagnostics can outlive their request and move through systems with different access rules. Record safe identifiers and classifications at the boundary that understands data sensitivity, using explicit protected workflows for rare sensitive evidence.PatternDocumentationSource TruthLocal ConventionsBootstrap Repo Docsbootstrap-repo-docsRepositories without a documentation map make newcomers infer structure from scattered files and conventions. Add the smallest durable entry points that explain purpose, layout, commands, and where deeper guidance belongs.PatternAgent WorkflowVerificationFeedback LoopsBudget Tokens For Feedback Loopsbudget-tokens-for-feedback-loopsLong-running agent work can exhaust context before validation, review, or handoff happens. Reserve space for feedback loops by summarizing durable state and avoiding unnecessary transcript growth.PatternAgent WorkflowDocumentationDeliver Context Just In Timedeliver-context-just-in-timeToo much context up front overloads the reader, while too little context forces rediscovery. Provide the next useful fact at the point of decision, linking outward when deeper background is optional.PatternSource TruthDocumentationLocal ConventionsDistill From Blessed Artifactsdistill-from-blessed-artifactsDurable guidance should come from accepted examples, reviewed decisions, and working artifacts rather than transient preferences. Distill stable lessons from blessed sources and keep uncertain ideas marked as draft.PatternDocumentationSource TruthDocument System Mental Modelsdocument-system-mental-modelsSystems with implicit concepts force readers to reconstruct how parts fit together from scattered implementation details. Document the mental model that explains ownership, flow, boundaries, and vocabulary before listing procedures.PatternAgent WorkflowSource TruthAutomationGarbage Collect Agent Driftgarbage-collect-agent-driftAgent-generated notes, plans, and assumptions can outlive their usefulness and mislead later work. Periodically remove, update, or promote them so durable guidance stays current and temporary scaffolding does not become false context.PatternAgent WorkflowBoundary CorrectnessGive Agents Objectives With Boundariesgive-agents-objectives-with-boundariesAgents perform better when they know both the desired outcome and the limits around scope, authority, and risk. State objectives with concrete boundaries so the agent can act autonomously without expanding the task accidentally.PatternAgent WorkflowVCS JJOwnershipIsolate Agent Workspacesisolate-agent-workspacesShared worktrees make it easy for agent edits, generated files, or validation steps to collide with unrelated work. Use isolated workspaces when concurrent tasks or uncertain changes need clear ownership and cleanup.PatternSecurity PrivacyKeep Secrets Out Of Contextkeep-secrets-out-of-contextSecrets and private data can leak through prompts, transcripts, logs, and generated artifacts even when the code change is harmless. Redact or replace sensitive values before they enter shared context, and use controlled channels when real secrets are required.PatternReader LocalityReviewabilityLimit Live Contextlimit-live-contextReaders make mistakes when they must keep too many facts active to understand a change. Reduce live context by moving related facts together, naming intermediate concepts, and keeping dependencies local.PatternState TransitionsObservabilityMake Runtime State Agent Legiblemake-runtime-state-agent-legibleAgents can only validate behavior reliably when the relevant runtime state is observable through their tools. Expose the smallest useful signal first, such as app boot, UI inspection, logs, metrics, screenshots, traces, or generated artifacts.PatternAgent WorkflowSource TruthManage Agent Work Not Sessionsmanage-agent-work-not-sessionsInteractive sessions do not scale when the maintainer must remember every thread, terminal, and handoff. Represent agent work as durable tasks with states, owners, validation, and review criteria so humans spend attention on priorities and judgment.PatternAgent WorkflowReader LocalityOptimize For Agent Legibilityoptimize-for-agent-legibilityRepositories that are hard for agents to inspect, search, run, and validate make delegated work slower and less reliable. Prefer structures, commands, names, examples, and runtime signals that help both agents and human maintainers reason locally.PatternDocumentationSource TruthPrefer Durable Summariesprefer-durable-summariesImportant context is costly when every reader must rediscover it from implementation details, but exhaustive narration becomes stale. Capture stable invariants, rationale, boundaries, or side effects in short summaries that survive nearby changes.PatternAgent WorkflowReview HandoffPreserve Agent Context Coherencepreserve-agent-context-coherenceMixing unrelated work pollutes the sessions attention, working-copy state, and handoff narrative. Keep each session and jj change focused on one purpose, splitting work when ownership, validation, or review decisions diverge.PatternAgent WorkflowReview HandoffPreserve Intent Over Literalismpreserve-intent-over-literalismLiteral compliance can violate the users actual goal when a request touches risky, privileged, or externally visible actions. Infer the safe operating intent and stop when policy, review expectations, or irreversible consequences conflict with the words alone.PatternToolingFailure OutputShape Tool Output For Agentsshape-tool-output-for-agentsHuman-oriented tool output can bury the failure signal an agent needs to act. Prefer quiet summaries, structured output, and saved full logs so agents see the actionable slice first without losing debugging context.PatternDocumentationLocal ConventionsUse AGENTS.md As Mapuse-agents-md-as-mapA giant AGENTS.md grows stale and crowds out the context the agent actually needs. Keep it as a compact map to canonical guides, patterns, commands, and safety rules, with details living in owned files.PatternDocumentationSource TruthUse Disk As Context Sinkuse-disk-as-context-sinkLarge pasted context is difficult to search, diff, summarize, and revisit. Put bulky or reusable context on disk so agents can pull the relevant slice while the thread stays focused on decisions and handoff.

PrincipleAgent WorkflowToolingAutomationAgent Instructions Are Operational Controlsagent-instructions-are-operational-controlsAgent instructions should change future behavior, not merely restate a preference. Compact rules need enough trigger, purpose, and boundary context for agents to apply them without blind literalism.PrincipleReview HandoffDocumentationSource TruthPrivate Context Is Not Shared Contextprivate-context-is-not-shared-contextShared artifacts must carry the reasoning that downstream readers did not see in the private session. Issues, PRs, commits, guides, and review packets should restate the decision context that matters.

MechanismVCS JJAgent WorkflowToolingJJ Agent Workflowjj-agent-workflowNoninteractive jj defaults, topology checks, and local override conventions make agent source-control work safer. The mechanism keeps local workflow state explicit without leaking private checkout assumptions into shared artifacts.MechanismDocumentationSource TruthReviewabilityProject Operating Manualproject-operating-manualA project operating manual is a repo-owned document that applies broad software guidance to one live codebase. It turns a large catalog of durable rules into an opinionated project-specific doctrine, decision surface, and review contract so maintainers and agents do not have to reconstruct the totality of what matters here from AGENTS.md plus many scattered guides.

AgentAgent WorkflowReviewabilitySource TruthApply Practice Guidanceagent-apply-practice-guidanceCompact instructions for Codex sessions that need to use the shared practice catalog from another repository. The snippet turns broad standards into a task-local application loop without loading the whole catalog or treating preferences as automatic churn.AgentAgent WorkflowToolingReview HandoffCoding Agent Workflow Instructionsagent-coding-workflow-instructionsCompact workflow instructions for repositories that delegate implementation or review work to coding agents. The snippet emphasizes objectives, boundaries, durable handoff, repo-owned context, and feedback that becomes reusable guidance.AgentAgent WorkflowReview HandoffVerificationCore Agent Instructionsagent-core-instructionsBroad baseline instructions for coding agents working in repositories that adopt these development preferences. The snippet keeps AGENTS.md short while routing agents to canonical guides, principles, mechanisms, and the reviewed rule pack.AgentDocumentationSource TruthReviewabilityFull Documentation Doctrine Prompt Packagent-full-documentation-doctrine-prompt-packLarge single-file prompt pack for long-term documentation maintenance. It combines the repos docs rules with writing, review, anti-drift, and anti-AI-slop lessons drawn from this repo, TidySrc, jk, and Komodo-style documentation cleanup work.AgentAgent WorkflowSource TruthReviewabilityFull Software Doctrine Prompt Packagent-full-software-doctrine-prompt-packLarge single-file prompt pack that combines the repos software rules and the reasons behind them into one coherent artifact. This version is tuned for Rust-heavy maintenance and refactoring work, especially when existing code needs to be reshaped toward better locality, coherence, ownership, and documentation.