Chain of context rule

A developer introduced 'Chain of Context,' an operating model for organizing project files to be navigable by stateless AI agents. The approach uses clear naming conventions, structured folders, and hyperlinks to enable progressive discovery, reducing the need for human re-explanation. It aims to save time, tokens, and money by turning the filesystem into a memory scaffold.

Chain of context is an operating model for making projects navigable by stateless agents. It is a way to organize files for agent ergonomics: make the filesystem easy to scan, sort, follow, and trust. The core idea: a human or AI agent should be able to land in a repo or folder, run ls and grep, read a few well-named files, follow links, and reconstruct what happened without needing a person to re-explain it. This matters because LLM sessions are stateless by default. They start cold. If the project is a pile of download.txt , notes-final-v2.md , and disconnected artifacts, the agent loses time rediscovering context and risks making bad assumptions. If the project is organized for progressive discovery, the filesystem becomes the memory scaffold. Chain of context turns the working environment into onboarding. The environment should answer: - What is this? - When did it happen? - Why does it matter? - What is the source of truth? - What should I read next? No single file needs to explain everything. Each file only needs to be named clearly, placed correctly, and linked to the next useful piece of context. Names should carry meaning. When a file is tied to a date, put the ISO date first: YYYY-MM-DD-description.md . This makes plain filesystem views sortable and lets agents reconstruct sequence from ls before opening anything. Use names like: 2026-04-05-first-meeting-summary.md status-report-feedback-classification.md 2026-05-26-roadmap-weekly-dependencies.md Avoid names like: download.txt notes.md final-v2-real.md A future agent should understand the rough purpose of a file from reading it before opening it. Structure should work like a CLI or a small wiki: - shallow overview first - deeper detail second - source artifacts last The agent should be able to move from folder → README/index → dated note → source transcript/MR/email/doc without guessing. Good structure lets context accumulate gradually instead of requiring a giant upfront explanation. This saves time, tokens, and money. Use hyperlinks/addressable pointers as connective tissue. Prefer linking to the source of truth over duplicating it. A durable note can summarize, but it should point to the artifact, transcript, issue, PR, email, or doc that supports the summary. The goal is not to create more prose. The goal is to preserve navigability. These serve different jobs. They are not prerequisites and can be overkill. Use them contextually. The front door for a folder. Use it to answer: - what this folder is - what is current - where the important files live - what someone should read next README.md works well for folders in a repo. index.md works well for wiki-style folders. They should orient, not explain everything. Good entry shape: Project Name One-sentence purpose. Current - Status: active - Source of truth: Hosted doc https://example.com Map - daily-log/ daily-log/ — dated breadcrumbs - research/ research/ — durable topic notes - sources/ sources/ — source artifacts and exports Contextual operating rules for agents. Use it for behavior and constraints an agent should follow in this folder: - source-of-truth rules - sync rules - naming conventions - commands to run before editing - things not to touch - local workflow expectations The root AGENTS.md should stay high-level. Nested AGENTS.md files can be more specific to a folder, dataset, client, or workflow. Good entry shape: Agent Instructions - Read README.md first. - Preserve source artifacts; summarize by linking to them. - Before editing data/current.csv , pull the hosted source and confirm parity. - Add short dated breadcrumbs to daily-log/ when project state changes. A dated, append-only chain-of-context index. Use it for what happened today: - branch created - MR opened - eval run - doc updated - meeting transcript saved - subtle bug diagnosed - local state changed Keep entries short. Link to the artifact. Do not duplicate the artifact. 1 file per day is good. Good entry shape: 2026-06-09 - 14:25 — Linked data/current-metrics.csv to hosted spreadsheet <spreadsheet-id ; sync rules in data/AGENTS.md . - 14:40 — Saved meeting summary in meetings/2026-06-09-planning-summary.md ; source transcript remains in sources/ . Topic-organized knowledge that should be findable later. Use it for refined understanding: - architecture - product decisions - data model discoveries - recurring workflows - implementation notes - refined and meaningful research Update these when understanding changes. The idea is taken from here: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f - use this as reference but don't let it over complicate things. Preferences about how to work, not project state. Use memory for durable collaboration preferences, not for branches, commits, or one-off project facts. Memories should be the concern of Agents and not saved in repo. example-project/ README.md AGENTS.md daily-log/ 2026-06-09.md research/ workflow-notes.md sources/ 2026-06-09-meeting-transcript.md outputs/ 2026-06-09-project-brief.md The README.md orients. AGENTS.md tells agents how to behave. daily-log/ preserves sequence. research/ holds durable understanding. sources/ preserves provenance. outputs/ holds deliverables. When deciding where something goes, ask: - Is it the front door for a folder? Put it in README.md or index.md . Does it help create a mental map quickly? - Is it an operating rule for agents? Put it in AGENTS.md . - Is it dated and tied to what happened in a session? Put a short pointer in the daily log. - Is it durable and should be findable by topic? Put it in the wiki or a research/doc folder. - Is it a source artifact? Preserve it with a descriptive name and link to it. ALWAYS LET THE DOMAIN DRIVE THE ARCHITECTURE. These are guidlines. The philosophy is more important. Coding agents do not need perfect memory if the project has a good chain of context. They need: - names that explain themselves - folders that imply where to go next - indexes that orient quickly - links that preserve provenance - daily breadcrumbs that show sequence This reduces repeated rediscovery, prevents context drift, and makes it easier for future sessions, teammates, and agents to pick up without re-deriving decisions. In short: chain of context is not documentation overhead. It is information architecture for stateless collaborators.