Skip to content

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

Description

@mmcky

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

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions