[PR #148] [MERGED] docs: add CLAUDE.md shim importing AGENTS.md #149

New issue

Closed

opened 2026-10-31 22:05:02 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:05:02 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/148
Author: @mattmillerai
Created: 9/16/2026
Status: ✅ Merged
Merged: 10/9/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-3575-claude-md-shim

📝 Commits (2)

4f1142f docs: add CLAUDE.md shim importing AGENTS.md
ef66247 docs: anchor the CLAUDE.md prettierignore entry to the repo root

📊 Changes

2 files changed (+11 additions, -0 deletions)

View changed files

📝 .prettierignore (+9 -0)
➕ CLAUDE.md (+2 -0)

📄 Description

ELI-5

Claude Code only reads CLAUDE.md; it never falls back to AGENTS.md. This repo
already has a rich AGENTS.md but no CLAUDE.md, so Claude Code was seeing no
instructions at all. This adds a tiny CLAUDE.md that just says "the real
instructions are in AGENTS.md" and imports it, so both Claude Code and every
other agent tool read the same single source of truth.

What & why

Per the org "Pillar 1: Agentic Engineering" standard, a repo's agent instructions
live in a top-level AGENTS.md, and CLAUDE.md exists only as a shim that
imports it (Claude Code reads CLAUDE.md, not AGENTS.md, with no fallback).

AGENTS.md already exists on the default branch (added in #60 and maintained
since). The only missing piece was the shim, so this PR adds exactly that:

CLAUDE.md — the canonical two-line shim: an HTML comment explaining the
arrangement, followed by @AGENTS.md. Content is byte-identical to the org's
canonical form so every repo's shim matches.
.prettierignore — a root-anchored exclusion for /CLAUDE.md (see judgment
call below). The leading slash matters: this file uses gitignore syntax, so a
bare CLAUDE.md would match at any depth and also exempt a future nested shim.
Anchoring scopes the exemption to exactly the root file the comment describes.

No .cursorrules exists (correct — legacy), and there are no nested AGENTS.md
files, so no nested shims are needed. AGENTS.md itself is left untouched.

Verification (all local gates from AGENTS.md §4, green)

pnpm lint (oxlint) — pass
pnpm format:check (oxfmt) — pass (83 files; CLAUDE.md excluded)
pnpm typecheck (tsc --noEmit) — pass
pnpm check:spec-drift — pass
pnpm test (vitest) — 620 passed / 26 files
pnpm build — pass
node scripts/check-public-repo-hygiene.mjs — pass (the shim carries no
ticket-shaped identifiers, internal links, or repo references)

Judgment call — excluding `CLAUDE.md` from oxfmt

This repo runs oxfmt over Markdown (format:check is part of the test job).
oxfmt wants to insert a blank line between the HTML comment and the @AGENTS.md
import, which would make this repo's shim diverge from the org's canonical
byte-for-byte form. That put two acceptance requirements in direct tension:
"exactly the canonical shim content" vs "CI green".

I resolved it by keeping the shim byte-exact and excluding it from oxfmt in
.prettierignore — the same mechanism the repo already uses for artifacts whose
exact bytes must not be reformatted (generated code, the parity snapshot). The
canonical shim is precisely that class of fixed artifact: its whole purpose is to
be identical across every repo. The alternative (accept oxfmt's blank line, no
.prettierignore change) is a smaller diff but would leave this repo's shim
diverging from the standard, so I chose byte-exactness.

Residual

AGENTS.md exceeds the 200-line target. The org standard asks for a root
AGENTS.md under 200 lines; the pre-existing file is 247 lines. This PR leaves
it unchanged, because the task is to leave AGENTS.md content unchanged unless
explicitly asked to trim/merge, and it was authored and verified independently
(not by this change). Trimming it to <200 lines — by pushing subsystem detail
(the section 2 spec-coupling catalogue is the bulk) into a nested doc or file —
is a separate, self-contained follow-up that a human can pick up without this PR
open.

Provenance

Authored by: agent-work loop
Verified: all AGENTS.md §4 local gates re-run and green on the final tree
(lint, format:check, typecheck, spec-drift, 620 tests / 26 files, build,
public-repo-hygiene); CLAUDE.md confirmed byte-identical to the canonical
shim (unchanged by the anchoring commit); confirmed no nested AGENTS.md and
no .cursorrules. The /CLAUDE.md anchoring was verified empirically, not by
reading the docs: with a deliberately misformatted nested CLAUDE.md in the
tree, format:check skipped it under the bare pattern (83 files, pass) and
flagged it under /CLAUDE.md (84 files, fail), while the root shim stayed
excluded under both.
Deviations: added a .prettierignore entry beyond the bare CLAUDE.md
file (the judgment call above) — the only way to satisfy both "exactly canonical
content" and "CI green" simultaneously.

Summary by CodeRabbit

Documentation
- Added guidance for maintaining shared project instructions through a centralized reference.
- Preserved the canonical formatting of the project’s instruction content.
- Ensured formatting rules leave the root instruction file unchanged while continuing to apply appropriately to similarly named files elsewhere in the project.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-typescript-sdk/pull/148 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 9/16/2026 **Status:** ✅ Merged **Merged:** 10/9/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-3575-claude-md-shim` --- ### 📝 Commits (2) - [`4f1142f`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/4f1142f856ca0ad50a990c1633a5b5d171bee44e) docs: add CLAUDE.md shim importing AGENTS.md - [`ef66247`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/ef66247ede985df5d8e55d8c3f2ef59b3f6a15f0) docs: anchor the CLAUDE.md prettierignore entry to the repo root ### 📊 Changes **2 files changed** (+11 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `.prettierignore` (+9 -0) ➕ `CLAUDE.md` (+2 -0) </details> ### 📄 Description ## ELI-5 Claude Code only reads `CLAUDE.md`; it never falls back to `AGENTS.md`. This repo already has a rich `AGENTS.md` but no `CLAUDE.md`, so Claude Code was seeing no instructions at all. This adds a tiny `CLAUDE.md` that just says "the real instructions are in `AGENTS.md`" and imports it, so both Claude Code and every other agent tool read the same single source of truth. ## What & why Per the org "Pillar 1: Agentic Engineering" standard, a repo's agent instructions live in a top-level `AGENTS.md`, and `CLAUDE.md` exists **only** as a shim that imports it (Claude Code reads `CLAUDE.md`, not `AGENTS.md`, with no fallback). `AGENTS.md` already exists on the default branch (added in #60 and maintained since). The only missing piece was the shim, so this PR adds exactly that: - **`CLAUDE.md`** — the canonical two-line shim: an HTML comment explaining the arrangement, followed by `@AGENTS.md`. Content is byte-identical to the org's canonical form so every repo's shim matches. - **`.prettierignore`** — a root-anchored exclusion for `/CLAUDE.md` (see judgment call below). The leading slash matters: this file uses gitignore syntax, so a bare `CLAUDE.md` would match at any depth and also exempt a future nested shim. Anchoring scopes the exemption to exactly the root file the comment describes. No `.cursorrules` exists (correct — legacy), and there are no nested `AGENTS.md` files, so no nested shims are needed. `AGENTS.md` itself is left untouched. ## Verification (all local gates from AGENTS.md §4, green) - `pnpm lint` (oxlint) — pass - `pnpm format:check` (oxfmt) — pass (83 files; `CLAUDE.md` excluded) - `pnpm typecheck` (tsc --noEmit) — pass - `pnpm check:spec-drift` — pass - `pnpm test` (vitest) — 620 passed / 26 files - `pnpm build` — pass - `node scripts/check-public-repo-hygiene.mjs` — pass (the shim carries no ticket-shaped identifiers, internal links, or repo references) ## Judgment call — excluding `CLAUDE.md` from oxfmt This repo runs oxfmt over Markdown (`format:check` is part of the `test` job). oxfmt wants to insert a blank line between the HTML comment and the `@AGENTS.md` import, which would make this repo's shim diverge from the org's canonical byte-for-byte form. That put two acceptance requirements in direct tension: "exactly the canonical shim content" vs "CI green". I resolved it by keeping the shim byte-exact and excluding it from oxfmt in `.prettierignore` — the same mechanism the repo already uses for artifacts whose exact bytes must not be reformatted (generated code, the parity snapshot). The canonical shim is precisely that class of fixed artifact: its whole purpose is to be identical across every repo. The alternative (accept oxfmt's blank line, no `.prettierignore` change) is a smaller diff but would leave this repo's shim diverging from the standard, so I chose byte-exactness. ## Residual - **`AGENTS.md` exceeds the 200-line target.** The org standard asks for a root `AGENTS.md` under 200 lines; the pre-existing file is 247 lines. This PR leaves it unchanged, because the task is to leave `AGENTS.md` content unchanged unless explicitly asked to trim/merge, and it was authored and verified independently (not by this change). Trimming it to <200 lines — by pushing subsystem detail (the section 2 spec-coupling catalogue is the bulk) into a nested doc or file — is a separate, self-contained follow-up that a human can pick up without this PR open. ## Provenance - **Authored by:** agent-work loop - **Verified:** all AGENTS.md §4 local gates re-run and green on the final tree (lint, format:check, typecheck, spec-drift, 620 tests / 26 files, build, public-repo-hygiene); `CLAUDE.md` confirmed byte-identical to the canonical shim (unchanged by the anchoring commit); confirmed no nested `AGENTS.md` and no `.cursorrules`. The `/CLAUDE.md` anchoring was verified empirically, not by reading the docs: with a deliberately misformatted nested `CLAUDE.md` in the tree, `format:check` skipped it under the bare pattern (83 files, pass) and flagged it under `/CLAUDE.md` (84 files, fail), while the root shim stayed excluded under both. - **Deviations:** added a `.prettierignore` entry beyond the bare `CLAUDE.md` file (the judgment call above) — the only way to satisfy both "exactly canonical content" and "CI green" simultaneously.  ## Summary by CodeRabbit - **Documentation** - Added guidance for maintaining shared project instructions through a centralized reference. - Preserved the canonical formatting of the project’s instruction content. - Ensured formatting rules leave the root instruction file unchanged while continuing to apply appropriately to similarly named files elsewhere in the project.  --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:05:02 +00:00