Agent context
Instructions and durable project facts loaded for an agent's current task.
45 items in this guidance cluster.
Tagged guidance
Guide item
Agent workflow rules
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.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.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.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.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.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.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.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.
Boundary rules
Documentation rules
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.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.
Review rules
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.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.
Source rules
Pattern items
Ask 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.Avoid 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.Bootstrap 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.Budget 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.Deliver 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.Distill 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.Document 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.Garbage 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.Give 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.Isolate 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.Keep 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.Limit 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.Make 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.Manage 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.Optimize 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.Prefer 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.Preserve 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.Preserve 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.Shape 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.Use 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.Use 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.
Principle items
Agent 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.Private 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.
Mechanism items
JJ 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.Project 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.
Agent items
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.Coding agent 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.Core agent 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.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.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.