QuantEcon / QuantEcon/quantecon-book-theme

docs: add CLAUDE.md and refresh stale parts of copilot-instructions.md

Open
#391 0 comments 0 reactions 0 assignees View on GitHub

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

🤖 Generated with Claude Code

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.