docs: write project CLAUDE.md with layout, commands, and contribution conventions - #36
Merged
Merged
Conversation
|
castastrophe
commented
Jul 17, 2026
… conventions The previous CLAUDE.md contained only a stray Cursor-style frontmatter block and no actual guidance. Replace it with real project instructions so coding agents can work in the repo without re-deriving its structure. The new file covers the four-file flat layout, the yarn commands for tests, coverage, and JSDoc type-checking, and the conventions that are easy to violate silently: JSDoc accuracy on exports (published types are generated from it), real-tempdir test patterns, the Weaver-managed README blocks, and the local-first no-dependency-creep constraint. It also documents the Conventional Commits and squash-merge PR rules that commitlint and semantic-release enforce.
Co-authored-by: [ Cassondra ] <castastrophe@users.noreply.github.com> Signed-off-by: [ Cassondra ] <castastrophe@users.noreply.github.com>
castastrophe
force-pushed
the
cl/review-claude-md-guidelines-0d432d
branch
from
July 17, 2026 20:28
83d027d to
41270ee
Compare
Minimum allowed line rate is |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Replace the effectively empty CLAUDE.md (a stray Cursor-style frontmatter block with no content) with real project instructions for coding agents.
Why
Agents working in this repo had no guidance to load — the file carried zero information, so every session re-derived the project layout, commands, and conventions from scratch (or missed them entirely, e.g. the Weaver-managed README blocks).
How
The new file is ~60 lines, organized so a smaller model can act on it without exploring first:
index.js,cli.js,mcp.js,test.js); explicit note that there is nosrc/yarn test/coverage/typecheck/build:types, with the Yarn 4 + Node ≥ 24 requirementweaver:*:START/ENDmarkers, and the husky hook behaviorEverything documented was verified against the repo (package.json, configs, hooks, source) rather than written from assumption.
Test plan
Docs-only change; no runtime surface. Verified the commit passed the pre-commit (lint-staged/prettier) and commit-msg (commitlint) hooks locally.
yarn test) — n/a, docs onlyyarn eslint .)yarn typecheck) — n/a, docs only