Skip to content

docs: add progressive-disclosure agent guidance - #349

Closed
zguesmi wants to merge 1 commit into
mainfrom
pr/d-agent-guidance
Closed

docs: add progressive-disclosure agent guidance#349
zguesmi wants to merge 1 commit into
mainfrom
pr/d-agent-guidance

Conversation

@zguesmi

@zguesmi zguesmi commented Aug 31, 2026

Copy link
Copy Markdown
Member

Independent of #346 / #347 / #348. Based on main, docs only, no code touched.

CLAUDE.md is the entry point an agent reads on every task, so it holds only what applies to every task, plus a table pointing at five topic files under .claude/context/:

File Read when
conventions.md creating or editing any file, committing, opening a PR
architecture.md changing contracts, storage, facets, deployment, chain config, orders, registries
commands.md running a command beyond package.json#scripts, reasoning about CI and generated files
testing.md writing or debugging tests, using the test helpers
upgrades.md scripting or executing a facet upgrade

The point of the split is cost: the entry point stays small enough to load every time, and the detail is pulled in only when the work touches it.

One file was missing

CLAUDE.md pointed at .claude/context/conventions.md, which did not exist — a dangling reference. It is written here, and collects the invariants that matter and are not derivable from the code: the SPDX header pair, the published surface in package.json#files (so ABI and artifact changes are public API changes), the append-only storage rule, the generated files that must never be hand-edited, the two hand-maintained facet lists in utils/proxy-tools.ts and scripts/tools/sol-to-uml.mjs, and the squash-merge / Conventional Commits rules.

Also

.claude/worktrees is added to .gitignore. Now that .claude/ is tracked, an agent worktree created inside the repository would otherwise show up as untracked files.

Follow-up if #348 lands

.claude/context/architecture.md names IexecInterfaceToken.sol and IexecEscrowTokenFacet, which is correct against main today. #348 retires both names, so whichever of the two merges second needs a one-line touch-up.

Verification

npm run format:check — All matched files use Prettier code style. No contract, test or script file is touched, so the build, storage, doc, typecheck and test gates are unaffected by this PR.

`CLAUDE.md` holds only what applies to every task, plus a table pointing at
five topic files under `.claude/context/`: conventions, architecture,
commands, testing and upgrades. An agent reads the entry point on every task
and pulls in a topic file only when the work touches it.

`.claude/context/conventions.md` is new here: `CLAUDE.md` pointed at it but the
file did not exist. It collects the repository invariants that were previously
inline: the SPDX header pair, the published surface in `package.json#files`,
the append-only storage rule, the generated files that must never be
hand-edited, the two hand-maintained facet lists, and the squash-merge and
Conventional Commits rules.

Also ignore `.claude/worktrees`, so agent worktrees created inside the
repository do not show up as untracked files now that `.claude/` is tracked.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@zguesmi
zguesmi requested a review from Le-Caignec as a code owner August 31, 2026 10:36
@zguesmi
zguesmi marked this pull request as draft August 31, 2026 10:42
@zguesmi zguesmi closed this Aug 31, 2026
@codecov

codecov Bot commented Aug 31, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.54%. Comparing base (26772eb) to head (fc94391).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #349   +/-   ##
=======================================
  Coverage   99.54%   99.54%           
=======================================
  Files          32       32           
  Lines        1095     1095           
  Branches      223      223           
=======================================
  Hits         1090     1090           
  Misses          5        5           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant