{"slug": "context-base-make-every-ai-agent-session-start-with-project-context", "title": "Context Base — make every AI agent session start with project context", "summary": "A developer released Context Base, a skill that helps AI agents understand a project before making changes by reading the repository, separating facts from guesses, and asking users only for context the code cannot reveal. The tool creates context files recording mission, priorities, decisions, constraints, and system maps, and is available for Claude Code, Codex, and other agents.", "body_md": "Context Base helps a fresh AI-agent session understand a project before it\nstarts making changes.\n\nIt reads the repository first, separates facts from guesses, and asks the user\nonly about context the code cannot reveal: mission, priorities, decisions, and\nconstraints.\n\nInstall\n\nDownload SKILL.md from this Gist.\n\nCreate a context-base folder inside your agent's skills directory.\n\nPut SKILL.md inside that folder.\n\nRestart the agent, then ask: Set up a context base for this project.\n\nCommon skill locations:\n\n```\nClaude Code: ~/.claude/skills/context-base/SKILL.md\nCodex:       ~/.codex/skills/context-base/SKILL.md\nShared:      ~/.agents/skills/context-base/SKILL.md\n```\n\nWhat it creates\n\nThe skill inspects the project and builds only the context files it needs. It\ncan record:\n\nconfirmed mission and priorities;\n\naccepted decisions and hard constraints;\n\na concise system map;\n\nverified workflows and conventions;\n\nimportant unknowns and conflicting evidence.\n\nIt does not invent product or architecture decisions. If the repository cannot\nanswer something important, it asks the user or records it as unknown.\n\nIncluded toolkit\n\nThe full lead-magnet download also includes 10 ready-to-copy Markdown templates\nfor projects that need a faster starting point.\n\nBuild, repair, or maintain a concise project context base that lets fresh AI-agent sessions understand a repository quickly and accurately. Use whenever the user asks for a context base, project memory, context-as-code, an agent briefing system, durable project knowledge, or better session-to-session continuity. Inspect the repository and its documentation before asking questions; separate verified facts, labeled inferences, and unknowns; ask the user only for missing mission, priorities, decisions, or constraints; and never invent product or architecture decisions.\n\nContext Base\n\nCreate durable project context that helps a fresh agent start like an informed\ncontributor. Treat context as maintained project infrastructure, not a large\nsummary of everything in the repository.\n\nCore standard\n\nA useful context base is:\n\nEvidence-backed: claims point to code, configuration, tests, or existing\ndocumentation.\n\nHonest: facts, inferences, and unknowns are visibly different.\n\nSelective: it records intent, decisions, boundaries, and navigation that\ncannot be recovered cheaply from source code alone.\n\nCurrent: volatile information is dated and easy to revise.\n\nNon-duplicative: it links to authoritative sources instead of copying them.\n\nSafe: it never stores secrets, credentials, private logs, or production data.\n\nDo not turn the context base into a second codebase, a speculative roadmap, or a\ntranscript dump.\n\n1. Establish scope\n\nInfer the requested project and outcome from the conversation. If the user asks\nfor a new context base, default to docs/context/ unless repository instructions\nor an existing convention specify another location. If a context system already\nexists, improve it in place rather than creating a competing one.\n\nBefore editing:\n\nFind and read every AGENTS.md, CLAUDE.md, or equivalent instruction file\nthat governs files you may touch.\n\nRead relevant source-of-truth files in full.\n\nPreserve unrelated work and follow the repository's own edit and validation\nrules.\n\n2. Inspect before interviewing\n\nInspect the project deeply enough to answer discoverable questions yourself.\nStart broad, then follow the paths that define behavior.\n\nRead, when present:\n\nroot and package READMEs;\n\nmanifests, lockfiles, workspace files, and build scripts;\n\napplication entry points and top-level module boundaries;\n\nschemas, migrations, API contracts, and generated-code notices;\n\ntests, CI workflows, deployment configuration, and environment examples;\n\ndocs/, ADRs, runbooks, changelogs, and existing plans;\n\nownership and contribution instructions;\n\nrecent version-control history only when it clarifies current intent.\n\nPrefer fast repository search and targeted inspection over reading every generated\nor vendored file. Never read or copy secret values from .env files. Environment\nvariable names may be recorded from safe examples or code references when useful.\n\n3. Build an evidence ledger\n\nBefore drafting durable context, sort every material claim into one of three\nclasses:\n\nFact: directly supported by inspected evidence or an explicit user\nstatement. Record the source path, document section, symbol, command output, or\nuser confirmation.\n\nInference: a plausible interpretation that is not explicitly established.\nLabel it Inference, explain the evidence briefly, and do not turn it into a\ndecision or requirement.\n\nUnknown: information that cannot be established safely. State what is\nmissing and why it matters.\n\nWhen sources disagree, do not silently choose one. Record the conflict, identify\nwhich source currently controls behavior, and leave intent unknown unless an ADR\nor user decision resolves it.\n\nUse this practical evidence order:\n\ncurrent executable behavior, schemas, and tests for what the system does;\n\naccepted ADRs and explicit user decisions for why and intended direction;\n\nrepository instructions for contribution and operating rules;\n\ncurrent operational docs and configuration;\n\nREADMEs, plans, comments, and history as supporting evidence.\n\nThis order is not absolute. A migration may prove current schema while an ADR\nstill owns the intended design. Describe both when they differ.\n\n4. Interview only for human-owned gaps\n\nFinish repository inspection first. Then ask only when a missing answer would\nmaterially change the context base and belongs to one of these categories:\n\nMission: who the project serves, the problem it exists to solve, and the\nintended outcome.\n\nPriorities: what matters now, ordering, deadlines, and what is explicitly\nnot a priority.\n\nDecisions: unresolved product, architecture, policy, or tradeoff choices.\n\nConstraints: hard business, legal, security, cost, compatibility, staffing,\nor operational limits.\n\nDo not ask the user to explain facts available in the repository. Do not ask for\nnice-to-have background. Group the smallest useful set of questions, explain the\nspecific gap each resolves, and provide the evidence already found so the user\ncan answer quickly.\n\nIf the user is unavailable, continue with verified facts. Put unresolved items in\nunknowns.md; do not fill the gaps with guesses. A context base with explicit\nunknowns is more trustworthy than a complete-looking fiction.\n\n5. Choose the smallest useful document set\n\nUse the templates in templates/ as starting points, not mandatory bureaucracy.\nRead templates/README.md before creating a new context base.\n\nAlways create or maintain a short entry point such as CONTEXT.md. Add other\ndocuments only when the project has durable information for them:\n\nmission-and-priorities.md for user-owned purpose and current focus;\n\ndecisions.md for accepted decisions and supersession history;\n\nsystem-map.md for boundaries and navigation, not file-by-file summaries;\n\nconventions.md for explicit and strongly observed rules;\n\nworkflows.md for verified commands and operating sequences;\n\nexternal-systems.md for integrations and ownership without secrets;\n\nunknowns.md for material gaps, conflicts, and labeled inferences;\n\nchange-log.md for material context updates.\n\nKeep authoritative artifacts where the repository already owns them. For example,\nlink to an ADR rather than restating its full rationale, and link to a schema\nrather than duplicating its fields.\n\n6. Write concise durable context\n\nWrite for both humans and agents. Use plain language, short sections, stable\nrelative paths, and explicit ownership.\n\nFor each material statement:\n\nstate only what helps future work;\n\ncite its source nearby;\n\ndistinguish current behavior from intended behavior;\n\ninclude Last verified: YYYY-MM-DD for volatile operational facts;\n\nname an owner only when evidence identifies one;\n\nuse Unknown instead of placeholders that look confirmed;\n\nremove duplicated explanation when a link to the authority is enough.\n\nNever invent a mission, priority, deadline, owner, requirement, architecture\nchoice, customer claim, or roadmap item. Recommendations must be labeled\nRecommendation and kept separate from accepted decisions.\n\nAvoid brittle line-number citations in durable files. Prefer a file path plus a\nstable heading, symbol, target, or key. Line numbers are useful only in the\nimmediate completion report.\n\n7. Make context loadable\n\nThe entry point should let a fresh agent answer four questions quickly:\n\nWhat is this project and what outcome does it serve?\n\nWhat is true now, and where is the proof?\n\nWhat matters now, and which decisions or constraints govern work?\n\nWhich document should be opened next for this task?\n\nKeep the default briefing small. Use an index and task-based reading routes so an\nagent loads detailed documents only when relevant. If repository instructions\nsupport it, add a short pointer from the existing agent instruction file to the\ncontext entry point; do not duplicate the context there.\n\n8. Validate\n\nBefore declaring completion:\n\nRe-open every created or changed context file.\n\nConfirm every fact has evidence and every inference is labeled.\n\nConfirm unknowns were not silently converted into decisions.\n\nCheck relative links and referenced paths.\n\nSearch for accidental secrets, tokens, private data, and placeholder claims.\n\nRun the repository's required documentation or project checks.\n\nReview the diff and remove duplication, stale wording, and unrelated changes.\n\nReport what was created, what was verified, which commands ran, and any human-owned\nunknowns that remain. Keep the report short.\n\nMaintenance rules\n\nUpdate context in the same change when a governing decision, boundary,\nworkflow, integration, or priority changes.\n\nAppend or supersede decisions; do not rewrite history to make an old decision\nlook as if it never existed.\n\nDate priorities and operational claims that can become stale.\n\nResolve unknowns by moving confirmed information into the owning document and\nrecording the resolution.\n\nPeriodically delete redundant context. More files do not mean better context.\n\nAnti-patterns\n\nDo not:\n\nask the user for architecture that the code already reveals;\n\ndescribe inferred behavior as a requirement;\n\ncopy whole READMEs, schemas, tickets, or source files into Markdown;\n\npreserve temporary implementation plans as permanent truth;\n\nrecord secrets or sensitive customer data;\n\ncreate parallel sources of truth;\n\nhide contradictions between docs and code;\n\nclaim the context base is complete when material unknowns remain.", "url": "https://wpnews.pro/news/context-base-make-every-ai-agent-session-start-with-project-context", "canonical_source": "https://gist.github.com/Maciejdziuba/294379d26ac117cf51df516efad4e403", "published_at": "2026-08-09 21:51:18+00:00", "updated_at": "2026-08-25 03:43:55.388758+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-products"], "entities": ["Context Base", "Claude Code", "Codex"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/context-base-make-every-ai-agent-session-start-with-project-context", "markdown": "https://wpnews.pro/news/context-base-make-every-ai-agent-session-start-with-project-context.md", "text": "https://wpnews.pro/news/context-base-make-every-ai-agent-session-start-with-project-context.txt", "jsonld": "https://wpnews.pro/news/context-base-make-every-ai-agent-session-start-with-project-context.jsonld"}}