27KB

Neapstrādāts Vainot Vēsture

Context Engineering — Chapter-31: Principles applied: chat, IDE, terminal and CI

Source: /library/Context Engineering/source-file.pdf
PDF pages: 285–305
Pages without text: none

Principles applied: chat, IDE, terminal and CI The work-in limit went from two to three on a Tuesday, by a decision of the coordinator, and you updated the project file the same day. On Thursday you ask the chat assistant for help writing the notice to the front desk, and it answers with the limit of two. You remember: that block of VilaSchedule rules is also pasted into the chat project instructions, and there it is still old. You fix it, and along the way you remember the third copy, the one that lives in the editor rules, which nobody has opened since April. Three copies of the same paragraph in three places that do not talk to each other, and the number they state is different in each one. None of them is wrong out of ignorance: you wrote all three, and all three were correct on the day they were pasted. What was missing was a single place all three came from. The second part of the problem is more expensive and less visible. Over the last few months you have learned where to click, which command to type and which file to edit in one specific tool, and you call that knowing how to use AI. Except 2026 has already renamed two of the tools cited in this chapter before the chapter was finished. Anyone who memorized the menu was left stranded; anyone who understood what the menu solved switched tools in an afternoon. This chapter exists to put you in the second group: it configures VilaSchedule, the scheduling system that has followed the book since Part II, in the four classes of tool you use, with every file printed right here.

Four questions before any configuration Every tool you are going to use answers, one way or another, four questions. The split is mine, an editorial choice and not an industry standard, and it is what I use before touching any new configuration:

Where does the persistent context live? On the vendor’s platform, in a file in your repository, in a file on your machine?
What does the tool inject into the window on its own, without your asking?
How much does a session cost before your first request?
What survives between one interaction and the next? A tool with the same four answers as another one gets the same treatment from you, however different the menus are. That is why I speak of a class: the useful grouping is not by vendor but by context behavior. The four classes in this chapter come out of that, and every tool cited is a dated instance of its class: a real example, verified in July 2026, and replaceable. Hold on to the order of the questions. The first decides where you write. The second decides what you do not have to write again. The third decides the size of what you write. The fourth decides what has to become a file before the session ends. The map of July 2026 Before the classes, the setting, because every name in this chapter carries a date. On the model side, Anthropic serves Claude Fable 5, Opus 5 and Sonnet 5; OpenAI serves GPT-5.5 as the ChatGPT default and GPT-5.6 in preview; Google serves Gemini 3.1 Pro; xAI serves the Grok 4 family, competitive above

all on price. On the benchmark aggregators, Fable 5 leads on SWE-bench Verified, with 95.0%, and Gemini 3.1 Pro leads on GPQA Diamond, with 94.3% (lmcouncil.ai/benchmarks, accessed in July 2026). Take one single thing from those numbers: the lead changes hands every quarter, all four vendors have a frontier model, and nothing in this chapter depends on the ranking of the month. Well-placed context works on whichever model is underneath. On the tool side, the same quarter delivered the proof that memorizing names is a bad strategy: Google retired Gemini CLI, its command line interface (CLI) agent, which stopped serving the standard plans on June 18, 2026, and replaced it with Antigravity CLI (developers.googleblog.com, “An important update: transitioning Gemini CLI to Antigravity CLI,” May 2026); and Windsurf, bought by Cognition, became Devin Desktop in June 2026, with the old documentation now published under the new name (docs.windsurf.com, accessed in July 2026). Both renamed tools answer the four questions exactly as their predecessors did. That is the pattern that matters. Chat assistant: the context lives outside the repository The class almost everyone started in. You talk in a product interface, the tool cannot see your disk, and the context that persists is what the platform keeps for you. The four instances of July 2026: ChatGPT, Claude, Gemini and Grok. Snapshot of July 2026: ChatGPT and Claude organize context by project, with their own instructions, files and history, and ChatGPT offers memory restricted to the project; Gemini uses Gems with knowledge files; Grok

combines custom instructions with automatic memory of conversations, on since April 2025. In Claude, a document base larger than the window turns on automatic retrieval in the paid plans. The box is the portrait that ages; what follows is what stays. All four answer the first question the same way: the persistent context lives on the platform, split between instructions, which hold what you would repeat in every conversation, and attached documents. In ChatGPT and Claude the unit is called a project: its own instructions, its own files and its own history per project (help.openai.com/en/articles/10169521 and support.claude.com/en/articles/9517075, accessed in July 2026). In Gemini the unit is called a Gem: instructions plus knowledge files saved with it (support.google.com/gemini/answer/15235603, accessed in July 2026). In Grok, custom instructions and workspaces separated by topic do the same job. The second question is where the class got trickiest in 2026: on top of what you wrote, in comes what the platform remembers on its own. Grok keeps automatic memory of your conversations since April 2025 (techcrunch.com/2025/04/16/xai-adds-a- memory-feature-to-grok, accessed in July 2026), and ChatGPT keeps general memory and, in new projects, lets you choose project-only memory, which isolates what the project learns from the rest of your account. If the clinic’s account also holds other topics, that isolation is the difference between context and contamination: without it, chapter 21 is violated by the platform itself, silently. The third question: every new conversation pays for the instructions in full plus whatever comes out of the documents. And here the warning of chapter 22 applies: the Claude

documentation records that, when the project document base grows beyond the window limit, automatic retrieval kicks in, expanding capacity up to tenfold in the paid plans (support.claude.com/en/articles/9517075, accessed in July 2026). A small base means you know what went into the window; a large base means a search you do not control, with the silent failures of that chapter. A document present in the base stops being a guarantee of a document present in the answer. The fourth: what survives is what is in the instructions and in the documents, never the conversation. A decision that stayed in the middle of a chat died there, as chapter 18 already told you. Down to work. None of those four platforms reads your repository, so what goes into them is always a copy, and a copy diverges, as the front desk notice proved. The discipline that fixes it is treating what is in the chat as a projection of something versioned, never as the source. This is the VilaSchedule projection I paste into the project instructions of all four, generated from the files you will see in the next sections:

VilaSchedule project instructions (projection for chat)

A projection of AGENTS.md and docs/conventions.md from the vilaschedule repository, generated on July 28, 2026. Do not edit this text here: edit the source in the repository and paste the projection again, with a new date. If this date is more than a month old,

distrust everything below and ask for the current projection. VilaSchedule is the scheduling system of Vila Nova Clinic: one schedule per provider in fixed 30-minute intervals, regular appointments and work-ins. Standing work-in limit: 3 per day, per provider (since July 14, 2026). Domain terms always match what the clinic says: Appointment, WorkIn, Provider; never a synonym and never a generic. A message shown to the front desk comes from the feature spec, copied literally; do not invent variations. Every answer about a scheduling rule must say which document in the repository the rule comes from. Look at the first two lines of the body: source and date. A copy with a declared source is a known debt, one anyone knows how to call in; a copy with no source is the wrong limit in the front desk notice. And look at the last sentence: asking that the answer cite the source document is the validation of chapter 19 built into the instruction. IDE agent: the context lives next to the code

Here the agent lives inside the editor, the integrated development environment (IDE), works on the same copy of the repository you do and sees the open project. The instances of July 2026: Cursor, VS Code with Copilot, Antigravity, which is Google’s IDE built on the same base as its terminal agent, and Windsurf, today Devin Desktop. Snapshot of July 2026: Cursor keeps .mdc rules in .cursor/rules , with four application modes and a workspace per worktree in multi-agent mode; Copilot reads .github/copilot-instructions.md and .instructions.md files by path pattern; Windsurf, bought by Cognition, became Devin Desktop in June 2026. All four read the repository’s AGENTS.md . The persistent context moves, and the move is the whole difference: it starts living in the repository, versioned with the code. In Cursor, project rules sit in .cursor/rules , versioned .mdc files, and there is a profile scope, outside the repository, for what is yours and not the project’s (cursor.com/docs/context/rules, accessed in July 2026). In Copilot, repository instructions sit in .github/copilot-instructions.md and in .instructions.md files with a declared path pattern (docs.github.com/en/copilot, “Adding repository custom instructions,” accessed in July 2026). In Devin Desktop, a global file in your profile coexists with the project rules, and the project’s win in a conflict (docs.windsurf.com, accessed in July 2026). The question that separates the scopes is the one from chapter 12: is this a clinic convention or a habit of yours? What the tool injects on its own depends on how each rule was marked, and this is where chapter 16 comes back wearing a product name. The Cursor documentation describes four application modes: always, by the agent’s decision from a

description, by file pattern and manual. Translated into the vocabulary you already have: the “always” mode is layer 0, charged in every session; the file pattern mode is the subsystem layer, which shows up only when you work in the matching slice; the manual one is a task packet. The pattern that ages badly is the single file marked “always” with everything inside, a database convention charged even in the session that only touches CSS. Splitting by file pattern is the packing of chapter 17, done once and collected forever. Down to work. At VilaSchedule, the only rule that deserves file pattern mode so far is the one about migrations, because it only concerns whoever touches migrations/ :

description: Rules for touching database migrations globs: [“migrations/**"] alwaysApply: false

A migration is written by hand, never generated; every up has a down tested before the commit.
File name: a three-digit sequential number and a verb in the

present tense, like 015-create-waitlist.sql.

A migration carries no business rule; the work-in limit lives in src/features/workins/, not in a database constraint. The rest of the project context needs no IDE format of its own, because the four instances of this class read the same neutral file the next section creates: Cursor reads AGENTS.md at the root and in subfolders; Copilot reads AGENTS.md anywhere in the repository, with the nearest one to the edited file winning, and accepts CLAUDE.md or GEMINI.md at the root as an alternative; Devin Desktop treats the root AGENTS.md as a rule for every session and the subfolder one as a rule by path pattern (sources for this section, accessed in July 2026). Write it once, let each editor load it its own way. What survives between interactions is what is in a file. What you explained in the editor’s side chat does not survive. The useful question at the end of a session where you corrected the agent three times is which of those corrections deserves to become a rule, and with which file pattern. Terminal agent: the context lives in directory layers The terminal agent runs in your shell, inside a working directory, and reaches whatever you authorize. It is the class I use the most, and the July 2026 one has four mature instances: Claude Code, from Anthropic; Codex CLI, from OpenAI; Antigravity CLI, from Google, whose command is agy ; and Cursor CLI, whose command is agent .

Snapshot of July 2026: Claude Code reads CLAUDE.md in four scopes and opens a parallel session in its own worktree with --worktree ; Codex CLI reads AGENTS.md and keeps global configuration in ~/.codex/ ; Antigravity CLI replaced Gemini CLI, retired from the standard plans on June 18, 2026, and keeps compatibility with GEMINI.md ; Cursor CLI reads the same rules as the Cursor IDE. The first question has the same answer in all four: markdown files, in more than one scope at the same time. Claude Code reads CLAUDE.md in four places, from the broadest to the most specific: the organization policy in a system path, your preferences in ~/.claude/CLAUDE.md , the project instructions in ./CLAUDE.md and your local preferences in ./CLAUDE.local.md , this last one outside version control (code.claude.com/docs/en/memory, accessed in July 2026). Codex CLI reads AGENTS.md in the project and keeps global configuration in ~/.codex/ , with an /init command that creates the project file (developers.openai.com/codex/cli, accessed in July 2026). agy reads AGENTS.md and keeps compatibility with its predecessor’s GEMINI.md (antigravity.google/docs, accessed in July 2026). Cursor CLI reads the same rules as the Cursor IDE, including AGENTS.md (cursor.com/docs/cli/overview, accessed in July 2026). Four scopes are four answers to “whose instruction is this”: the organization’s, yours, the repository’s, yours inside this repository. The URL of your test environment is yours; the naming convention of VilaSchedule belongs to the repository. The second question, in this class, has a property the others do not: the answer depends on where you are. The Claude Code documentation describes loading as a climb up the directory tree, from the working directory upward, with subdirectory files entering later, when the agent reads something in there; the same page recommends keeping each file under 200 lines,

because a long file eats context and reduces adherence to the instructions (code.claude.com/docs/en/memory, accessed in July 2026). It is chapter 17 in the words of the people who wrote the tool, and it holds as a criterion for all four instances: starting the session at the root or inside a feature folder changes what you pay and what the agent knows. Down to work, and this is the heart of the chapter. The single source of VilaSchedule is an AGENTS.md at the root of the repository. Abridged below, where [...] marks what did not fit on the page:

VilaSchedule

Appointment scheduling system for Vila Nova Clinic: one schedule per provider in fixed intervals, regular appointments and work-ins. [...]

Rules for every session

Domain terms match what the clinic says: Appointment, WorkIn, Provider. Never a synonym (Booking, Visit, Slot) and never

a generic (Item, Entity, Record).

An error message shown to the front desk comes from the spec, copied literally.
A database migration is written by hand and has a tested down.
New code is born inside src/features/<feature>/. Do not create a folder per technical layer, inside or outside the feature.
Nothing enters src/shared/ the first time it is used; only after two features need the same thing for the same reason.

What this file does not decide

The context specific to each feature lives next to its code, in an AGENTS.md inside the feature folder. The work-in rules are in src/features/workins/AGENTS.md, and this file does not repeat them: two copies of the daily limit is exactly the problem the clinic already had.

Codex CLI, agy and Cursor CLI read that file directly. Claude Code reads CLAUDE.md , and the right answer to that is not to copy: it is an import bridge, printed here in full, that the Claude Code documentation itself recommends for repositories that already use the neutral file (code.claude.com/docs/en/memory, accessed in July 2026): This repository uses AGENTS.md as the single source of context. This file exists because Claude Code reads CLAUDE.md; it imports the source and adds nothing. @AGENTS.md And the rule that opened the chapter, the work-in limit, lives in a single file, inside the feature folder, where the four instances of this class and the four of the previous one find it when they work there:

Work-ins

Rules of the work-ins feature. This file is the only source of the daily limit; no other context file repeats it.

Standing limit: 3 work-ins per day, per provider. Coordination decided this on July 14, 2026; it was 2 until that date.
A work-in only goes into an open slot on the same day; there is no work-in scheduled for a future date.
When the day's limit is full, the front desk sees the message from the spec, copied literally: “Daily work-in limit reached for this provider.”
The limit calculation lives in day_limits.ts; a change of limit changes that file and this one, in the same pull request. When the coordinator changes the limit again, the change is one line in one file, and the chat projection is regenerated from it with a new date. Compare that with the opening of the chapter: this was what was missing. The fourth question closes the class: what survives is what is in a file, plus whatever the tool notes on its own when it has automatic memory, and the session itself dies. The habit chapter 18 asked for is still the only one that works. This class is also where the parallelism of chapter 21 becomes a button. In July 2026, Claude Code creates a git worktree per parallel session (the --worktree flag opens the session in a working directory of its own, on its own branch) and offers the same

isolation for subagents that edit files; Cursor, in multi-agent mode, gives each agent a workspace per worktree, and the pattern repeats in other tools of the class. The criterion for when to split is still the four conditions of chapter 21, and the mechanics are the ones from there: two subtasks with disjoint diffs, each on its own ground, coming back through the merge. What the tool adds is only the cost of entry: the worktree you used to create by hand now comes built in. Agent in CI: nobody there to correct course The fourth class, continuous integration (CI), is the one that most exposes what you failed to write. The agent runs on a server, fired by a repository event, and has nobody beside it to say “that is not what I meant” halfway through. The instances of July 2026: Claude Code in GitHub Actions, triggered by a mention in an issue or pull request (code.claude.com/docs/en/github- actions, accessed in July 2026); the Copilot coding agent, which runs in an ephemeral GitHub Actions environment with sessions capped at 59 minutes (docs.github.com/en/copilot, “About coding agent,” accessed in July 2026); Codex in the cloud, which runs the task in an isolated remote environment and hands back a pull request, and also reviews pull requests following the repository’s AGENTS.md (developers.openai.com/codex/integrations/github, accessed in July 2026); and the Cursor cloud agents, dispatchable from the IDE or the CLI to hand back pull requests (cursor.com/docs, accessed in July 2026). Snapshot of July 2026: Claude Code in GitHub Actions is triggered by a mention in an issue or pull request; the Copilot coding agent runs in an ephemeral environment with sessions of up to 59 minutes; Codex in the cloud runs in

an isolated remote environment, hands back a pull request and reviews pull requests by the AGENTS.md ; the Cursor cloud agents are dispatchable from the IDE or the CLI. The four questions have short, hard answers here. The persistent context is all the repository’s, and only that: there is no personal preferences file of yours, and unversioned information does not exist for the agent. What the tool injects on its own is the event that triggered it and whatever the workflow configuration declares; not even the code enters without the step that checks it out. The cost comes in two bills, server minutes and application programming interface (API) tokens, multiplied by the frequency of the event. And what survives is nothing, except what became a repository artifact: a commit, a pull request, a comment. An agent in CI that finds something out and writes it nowhere found it out for nobody. Down to work. VilaSchedule uses this class for what it does best, review with written rules, and the whole workflow fits on one page: name: pr-review on: pull_request: types: [opened, synchronize]

concurrency: group: review-${{ github.ref }} cancel-in-progress: true jobs: review: runs-on: ubuntu-latest timeout-minutes: 15 permissions: contents: read pull-requests: write steps: - uses: actions/checkout@v4 with: fetch-depth: 1

uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | Review the diff of this pull request against the rules in the root AGENTS.md and the AGENTS.md of every feature it touches. Flag only what violates a written rule, citing the file and the line of the rule. claude_args: “--max-turns 10” Read the file with the four questions in hand. The context the agent receives is the same AGENTS.md files from the previous sections, named in the prompt: zero duplication. The guardrails are written three times, a 15-minute timeout, concurrency that cancels a repeated run and a turn limit, because the third question here is charged per event, not per session of yours. And the prompt requires every finding to cite the written rule, which is the validation of chapter 19 in the one class where there is no second try: whatever is missing from the file becomes a wrong result published in the pull request, with the team’s name under it. Swapping this workflow for the Copilot coding agent or for Codex changes the syntax of the configuration file and nothing of the reasoning.

One source, four projections If you count the sections again, all of VilaSchedule ended up in five versioned files and one dated projection: the source at the root, the one-line bridge for Claude Code, the work-ins feature file, the migrations rule for the IDE and the CI workflow, plus the block pasted into the chat. Twelve tools from six vendors read that with no further configuration, and the convergence has had a name and an owner since 2025: AGENTS.md is an open standard, today maintained by the Agentic AI Foundation under the Linux Foundation, which describes it as a README for agents, defines that the nearest file in the tree wins and records more than 60,000 open source projects using the format (agents.md, accessed in July 2026). The rule I follow, and that the sections above applied without saying so, fits in three sentences. There is one source, versioned. A tool that reads another name gets an import bridge, never a copy of the paragraph. A tool that reads no file at all, like the chat assistant, gets a projection with a declared source and date, and the date works as an expiration date anyone knows how to check. “This will age the same way” The objection is the most serious one against this chapter, and it has half a point. What ages is the file name, the menu name and the limit the documentation recommends today. What does not age is the question that sent you looking for that file. The proof is in the very quarter this text was written: Gemini CLI became Antigravity CLI, Windsurf became Devin Desktop, and both went on reading the same AGENTS.md and answering the same four questions. Anyone with the setup in this section did not edit a single file.

The second objection is operational: “my team uses a tool that is not here.” That is the normal case, and it is what the chapter exists for. Pick the class by the answers, not by the logo. If the persistent context lives on the platform and nothing shows up in the repository, you are in the first class and the discipline of the dated projection holds in full. If the tool reads files from the repository climbing the directory tree, you are in the third, and its documentation answers the four questions in an afternoon. It is worth saying what this chapter assumes is already done. It tells you where to put the context, not how to write it. Without the spec of chapter 8, the living documentation of chapter 9, the architecture decision records (ADRs) of chapter 10, the conventions of chapter 11 and the context file of chapter 12, the four questions are still answerable and the result is useless: you will have found the exact place to put a context you never wrote. What degrades, without those artifacts, is the quality of what gets projected. The tool starts receiving well-placed improvisation, and no configuration fixes that. The context that never leaves your laptop Suppose you do everything this chapter asks. The five files in place, the dated projection, the work-in limit in a single file. Your first-pass rate goes up again, and this time you can say why. None of that reaches the team. The colleague who joined last month cloned the same repository and did not get your order of precedence, your criterion for what goes up to the root and your habit of declaring the date of the projection along with it. The context file they created on their machine diverges from yours in three places, and their agent has just recreated the work-in rule the clinic changed on Tuesday. The right context exists, written, verified, and it lives on one person’s laptop. Turning that into a

team asset, with a repository standard, governance and an entry path for whoever arrives tomorrow, is the subject of the next chapter.

27KB Neapstrādāts Vainot Vēsture