QuantEcon / QuantEcon/quantecon-book-theme
docs: add CLAUDE.md and refresh stale parts of copilot-instructions.md
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 56
- Forks
- 24
- Avg merge
- 4h 33m
- Merged PRs (30d)
- 4
Description
Background
We have `.github/copilot-instructions.md`
documenting project conventions for GitHub Copilot. We don't currently have
an equivalent for Claude Code, which auto-loads `CLAUDE.md` at the repo
root. Adding one makes Claude sessions in this repo aware of the same
project rules (tox-only-for-tests, asset-compilation workflow, release
process) without having to rediscover them every session.
While we're in there, the existing copilot-instructions.md has drifted from
the current state of the repo and needs a refresh.
Scope
1. Add a standalone `CLAUDE.md` at the repo root
Full content, written for Claude Code's idioms (no `tee /tmp` pattern,
HEREDOCs over create_file for gh commands, file_path:line_number
references, TodoWrite mentions for multi-step work). Mirrors the structure
of copilot-instructions.md so the two stay parallel on shared facts.
Should cover:
- Project overview
- Bootstrap (Python 3.13+, Node, tox, pre-commit, npm install)
- Build / test commands and timing
- Asset-compilation workflow (`npm run build` after editing
`src/quantecon_book_theme/assets/`) - Visual regression tests (new — uses
`quantecon-book-theme-fixtures`) - Code quality (pre-commit, flake8, black)
- Release process
- Project structure
2. Refresh `.github/copilot-instructions.md`
- Add a visual-regression-tests section covering the fixtures repo,
`tox -e visual`, and the `/update-new-snapshots` / `/update-snapshots`
PR-comment workflow. This was missing entirely. - Update the `package.json` snippet at line ~182. Currently shows
webpack 5.0.0 / sass 1.59 / css-loader 6.8 — actual versions are webpack
5.103 / sass 1.99 / css-loader 7.1, plus dev-only additions
(playwright/test, html-webpack-plugin, dedent, etc.). - Update the directory listing at line ~160 to include
`playwright.config.ts`, `.nvmrc`, and remove the inaccuracy that
`tests/test_build/` is the only thing under `tests/` (there's now
`tests/visual/`). - Optional: consider trimming the Copilot-specific shell-escaping
workarounds if they're stale.
Acceptance
- `CLAUDE.md` at repo root, full standalone content
- Visual-test / fixtures section added to copilot-instructions.md
- Stale package.json + directory listing fixed in copilot-instructions.md
- Both files agree on shared facts (build commands, test rules, release process)
Context
- Visual regression migration: #390
- Fixtures repo: https://github.com/QuantEcon/quantecon-book-theme-fixtures
🤖 Generated with Claude Code
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading .github/copilot-instructions.md, package.json, and the existing tests/visual/ workflow, including tox -e visual and the fixtures repository. Add the root CLAUDE.md and update the Copilot guide so both document the current bootstrap, build, visual-test, quality, release, and project-structure facts. Done means the acceptance checklist passes and the two guides agree on shared facts.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, playwright, python
- Domain
- developer-experience, documentation, testing-qa
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100