{"id":50968353,"url":"https://github.com/hyf0/project-context-records","last_synced_at":"2026-06-18T23:01:51.926Z","repository":{"id":364760990,"uuid":"1269100267","full_name":"hyf0/project-context-records","owner":"hyf0","description":"A context-engineering methodology: keep a durable, repo-versioned archive of a project's meta-context so AI collaborators inherit its judgment instead of re-deriving it.","archived":false,"fork":false,"pushed_at":"2026-06-14T10:54:04.000Z","size":49,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T12:18:19.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyf0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-14T10:01:19.000Z","updated_at":"2026-06-14T12:05:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyf0/project-context-records","commit_stats":null,"previous_names":["hyf0/project-context-records"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hyf0/project-context-records","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyf0%2Fproject-context-records","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyf0%2Fproject-context-records/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyf0%2Fproject-context-records/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyf0%2Fproject-context-records/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyf0","download_url":"https://codeload.github.com/hyf0/project-context-records/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyf0%2Fproject-context-records/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34510287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-18T23:01:51.069Z","updated_at":"2026-06-18T23:01:51.918Z","avatar_url":"https://github.com/hyf0.png","language":null,"funding_links":[],"categories":["🛠️ Tools \u0026 Projects"],"sub_categories":["Context Engineering Systems \u0026 Kits"],"readme":"# Project Context Records (PCR)\n\n**English** · [简体中文](./README.zh-CN.md)\n\n\u003e A methodology for the AI era: keep a durable, repo-versioned archive of a\n\u003e project's **meta-context** — the *why*, the architecture, the maintainer\n\u003e decisions, the intent — so that an amnesiac, self-directed AI collaborator\n\u003e inherits the project's judgment instead of re-deriving it.\n\u003e\n\u003e It is also a harness: a way for a human to keep hold of the direction while the\n\u003e AI iterates fast.\n\nPCR is a practice of **context engineering**. Context engineering curates what\ngoes into a model's context; PCR is the project-scoped, persisted slice of that\ncontext — the part worth versioning, reviewing, and inheriting across sessions.\n\n## TL;DR: How to use\n\n**Recommended — install the setup skill once, globally:**\n\n```\nnpx skills add hyf0/project-context-records -g\n```\n\nThen run `/pcr-setup` in any project to adopt PCR there. The global install (`-g`)\nmakes the command available across all your projects, and re-running it later\nupdates a project to the latest block. (Skill installs are powered by\n[skills.sh](https://www.skills.sh).)\n\n**Or do it by hand** — paste this block into your project's `AGENTS.md` /\n`CLAUDE.md` (point it at wherever you keep the records):\n\n```\n## Project Context Records (PCR)\n\nThis project follows **Project Context Records (PCR)** —\nmethodology: https://github.com/hyf0/project-context-records. PCR keeps the\nproject's durable design context — the *why*, the decisions, the architecture —\nso you inherit it instead of re-deriving or re-litigating what's already settled.\n\nWhen working here:\n- **Where they live.** Records are in `.agents/docs/` — one topic per file,\n  cross-linked with relative Markdown links (`[name](./name.md)`).\n- **Read first.** If a record covers the area you're touching, read it before acting.\n- **Record as you go.** Proactively write down context worth keeping — and whenever\n  a human asks you to. No required format, no fixed list of what qualifies: if it's\n  true about this project, not visible in the code, and useful beyond the moment,\n  it's worth a record.\n- **Keep it fresh.** If your change affects a record, update it in the same change —\n  a stale record is a trap, not an asset.\n- **Provenance.** An unstamped line is AI-accumulated: challenge and verify it freely.\n  A `[VOUCHED @handle]` stamp (on a line, or at the top of a file) means a human\n  vouched for it — treat it as settled; reopen or re-verify only on new evidence, a\n  changed constraint, or a human's say-so. Add a stamp only on a human's explicit\n  instruction; reading past a line, or not objecting, is not a stamp.\n```\n\nThat block *is* the whole adoption. It routes every collaborator — human or agent —\nto the records and states the rules they must follow. It is deliberately thin: an\nagent automatically reads `AGENTS.md` every session but does **not** fetch URLs, so\nonly what must be obeyed every session is inlined; the rest stays one link away and\nnever needs fetching for the agent to behave.\n\nThen just work: **accumulate** records freely as you go, and **distill** them —\npromoting the valuable, pruning the stale, stamping what a human vouches for —\nwhenever a human reviews.\n\n**Everything below is the *why*.**\n\n## Contents\n\n- [The premise: output is bounded by context](#the-premise-output-is-bounded-by-context)\n- [Why code is no longer enough](#why-code-is-no-longer-enough)\n- [Keeping the wheel](#keeping-the-wheel)\n- [Where it sits](#where-it-sits)\n- [Building on ADR](#building-on-adr)\n- [What goes in](#what-goes-in)\n- [The mechanism: the provenance stamp](#the-mechanism-the-provenance-stamp)\n- [Lifecycle: accumulate → distill](#lifecycle-accumulate--distill)\n- [Writing conventions](#writing-conventions)\n\n---\n\n## The premise: output is bounded by context\n\nAn LLM's output is a function of its context. Give it the context that decides the\nanswer and the result moves toward what the project wants; starve it and it fills\nthe gap with confident guesses — which is where wrong-but-plausible work comes from.\n\nThe asymmetry is the point. More context has trade-offs (noise, diluted attention,\ntokens); *missing the context that decides the answer* has none — it just loses. A\ncapable model reasoning without the deciding information still produces wrong work;\nits ceiling is set by what it can see.\n\nThis is why PCR has two halves: **accumulate** the judgment that would otherwise\nevaporate (too little is reliably bad), and **distill** it — pruning noise, keeping\nthe current truth fresh (too much or stale is bad too).\n\n---\n\n## Why code is no longer enough\n\nCode records the **result state**: what the system finally looks like. It\nstructurally drops three things a collaborator needs:\n\n1. **The rejected paths.** The code shows \"we chose A,\" never \"we considered B\n   and C; B was killed because X.\" So the next collaborator sees A, asks \"why\n   not B?\", tries B, and walks into the same wall.\n2. **The status of a choice.** Is this a deliberate, closed decision, or a\n   stopgap awaiting review? The code looks identical either way, but the two\n   call for opposite actions.\n3. **The provenance of a judgment.** On what constraints, trade-offs, and whose\n   call did this rest? When the constraints change, the decision may need\n   reopening — but only if you recorded what it was hanging on.\n\nIn the pre-AI era these lived in maintainers' heads and travelled by\n**continuity**: code review, mentorship, \"ask the person who wrote it.\" Teams\nwere continuous; the knowledge was tacit but unbroken.\n\nAn AI collaborator has **no continuity**. Every session is an amnesiac, capable,\nand *self-directed* newcomer. It does not \"ask the person who wrote it\" — it\nreasons, doubts, and acts on its own. Tacit knowledge is, to it, nonexistent. So\nthe judgment layer that always existed but hid in human heads must now be made\ninto an **explicit artifact** — or it re-evaporates, once per session, forever.\n\nPCR is that artifact. What it preserves is not *what the code is*, but *how the\njudgment was reached* — so that thinking already paid for is not paid for again.\n\n---\n\n## Keeping the wheel\n\nAI can iterate faster than any human can review. That forces a dilemma: review\nevery step and you become the bottleneck, erasing the speed; review nothing and\nthe work quietly drifts from what you wanted.\n\nPCR is a way out. A human sets direction at a few durable points — the records\nthey vouch for — and the AI runs fast within those rails. Control moves from\nreviewing every action, which doesn't scale, to owning the direction, which does.\nThe vouched stamp is the steering input: a vouched call isn't re-opened each\nsession without a real reason, so a decision you make once keeps shaping the work,\nsession after session, instead of being re-argued every time.\n\nSo PCR is also a **harness**: a way to hand the AI execution speed while a human\nkeeps the wheel. The scarce human act often shifts from doing the work, or checking\nit line by line, to setting and maintaining the direction the records encode.\n\n---\n\n## Where it sits\n\n```\nGuiding philosophy   Context Engineering   — curate what's in the model's context\n        └ Methodology   Project Context Records   — persist the project's slice of it\n                └ Mechanism   the provenance stamp   — mark who stands behind a claim\n```\n\n---\n\n## Building on ADR\n\nPCR is the AI-era descendant of **Architecture Decision Records (ADR)** — a\nconvention introduced by Michael Nygard in 2011 and since grown into an\n[ecosystem of tooling and templates][adr-hub]. An ADR records each significant\ndecision as a small, numbered, version-controlled file stating its *context*,\nthe *decision*, and its *consequences*; a decided record is never edited — to\nchange it, you write a new one that **supersedes** it, leaving an append-only\ntrail.\n\nPCR keeps ADR's best instinct — *knowledge lives in the repo, reviewed and\nversioned with the code, not in a wiki* — and adapts it in three ways for the new\nreader:\n\n1. **Decisions → context.** ADR centers one significant decision per file, with\n   its context and consequences. PCR widens the unit to the whole meta-layer:\n   decisions *and* architecture, mental models, deliberate divergences, gotchas,\n   and in-flight plans. A decision is one slice of a project's context, not all of it.\n2. **Immutable-and-stacked → single-and-fresh.** ADR preserves history by\n   freezing each decided file and appending a new one that supersedes it; the\n   current truth ends up scattered across that supersede chain. PCR keeps the\n   **current conclusion in one fresh place** and lets **git** hold the evolution.\n   An amnesiac agent re-reading a supersede chain to find today's answer is pure\n   waste; give it one trustworthy answer and send history to the log. Rationale\n   that still bears on the decision stays in the current entry; only the incidental\n   evolution goes to git.\n3. **Reader = human → reader = self-directed amnesiac agent.** ADR only\n   describes, because a human reads the consequences and self-regulates. An agent\n   will \"discover\" a settled thing and act on it. So a PCR entry may carry an\n   **action directive to the agent** (\"this is out of contract; don't re-flag\n   it\"), not just a description.\n\n---\n\n## What goes in\n\nThe **meta-layer** of a project: why it is shaped this way, the architecture,\nmaintainer decisions, intent, deliberate divergences, mental models, hard-won\ngotchas, and plans currently in flight.\n\nNegative definition, often sharper: **anything true about the project that the code\ncan't tell you, and that stays useful beyond the moment.**\n\nCapture is **broad** — record anything plausibly useful, cheaply, as you go,\nephemeral plans and in-flight reasoning included. Value is judged later, at\n**distillation** (below), not at capture time: what survives is the residue still\nuseful beyond the moment.\n\n---\n\n## The mechanism: the provenance stamp\n\nThis is the one piece of hard currency, and it rests on a first principle:\n\n\u003e In the AI era, text is cheap and **AI-authored by default**. The scarce,\n\u003e valuable act is a **human putting their seal on a claim.**\n\nSo the rule is a single bit:\n\n- **No stamp = AI-accumulated.** The default substrate. Treat it as\n  challengeable — question it, and verify it freely.\n- **`[VOUCHED @handle]` = a human vouched for it.** Treat it as foundation: don't\n  re-verify or reopen it for its own sake — do either only on new evidence, a\n  changed constraint, or a human's say-so. A stamp marks a single line (at the end\n  of it) or a whole file (at the top), and represents explicit human vouching: typed\n  by a human, or added by an agent only on a human's explicit instruction. A human\n  reading past a claim, or not objecting, never counts.\n\n```\nTimestamps are stored as UTC, converted only at the edges — settled after a DST bug.   [VOUCHED @hyf0]\n\nRaising the cache TTL to 1h is probably safe.   ← no stamp: AI-accumulated, verify freely\n```\n\n**The human seal is optional — for continuity, not for control.** The\nagent-accumulated substrate already carries the memory: an agent inherits what was\nrecorded, vouched or not. What the seal adds is the harness from [Keeping the\nwheel](#keeping-the-wheel) — the human direction that holds across sessions. So\nvouch where the stakes justify it, and leave the rest as the honest default.\n\n**Why a stamp, and only one kind.** The worst way an AI-maintained knowledge base\nfails is that the AI's own guesses get taken for facts a human has confirmed — a\nlater agent treats a machine-made assumption as settled and builds on it. The stamp\ndraws exactly that line, and only that line: **vouched for by a human, or not.**\nFiner distinctions — *decision or observation? settled or still tentative?* —\nbelong in the entry's own text, not in more kinds of stamp. Start with this one;\nadd more only if real use proves you need it.\n\n---\n\n## Lifecycle: accumulate → distill\n\n- **Accumulate** (cheap, default, by agents): record context proactively while\n  working — and whenever a human asks — and keep existing records fresh as your\n  changes touch them. Volume is fine; noise is expected.\n- **Distill** (scarce, by humans): a review pass that **promotes** the valuable,\n  **prunes** what's wrong or obsolete, and **vouches** for what holds — the part\n  agents can't do for themselves. This is the human seal applied as a recurring\n  practice, and where \"implementation plans tracked temporarily\" become \"the\n  valuable thing that remains.\"\n\n---\n\n## Writing conventions\n\n- **One topic per file.** Cross-link related entries with standard relative\n  Markdown links (`[other-topic](./other-topic.md)`) — clickable on GitHub,\n  unambiguous, and tool-agnostic.\n- **Keep the current truth fresh.** Drift is the death risk: a confident record\n  that no longer matches reality flips from asset to **trap** — an agent will act\n  on it with full confidence. A stale record is worse than no record. When your\n  change affects an entry, update the entry in the same change.\n- **Capture the why**, not just the what: the trade-off, the alternatives\n  rejected, the known pitfalls. Lead with the principle or intuition.\n- **Write so a collaborator gets it without reading the code internals.** The\n  entry stands on its own as prose; an agent reads it and *gets it*.\n- **No fixed format — on purpose.** A record is just prose that conveys the why.\n  A stricter shape may emerge from real use; don't impose one up front.\n\n---\n\n[adr-hub]: https://adr.github.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyf0%2Fproject-context-records","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyf0%2Fproject-context-records","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyf0%2Fproject-context-records/lists"}