Skip to content

Expand CLAUDE.md to match sibling section shape #13

Description

@loadfix

Problem

pptxjs' `CLAUDE.md` is 41 lines total with only 2 H2 sections (`OOXML feature workflow`, `Workflow`). The sibling JS/Python repos' CLAUDE.md files follow a much richer standard template:

  • Architecture
  • Source Layout
  • Key Patterns
  • OOXML feature workflow (required before adding rendering for any new feature)
  • Test Conventions
  • Commands
  • What NOT to do
  • Common workflows
  • Important

New contributors (and LLM agents) landing in pptxjs have no way to orient themselves without reading the full source tree.

Expected fix

Rewrite `CLAUDE.md` to mirror the 9-section canonical template used by python-docx / python-pptx / docxjs. Specifically add:

  • Architecture: the `src/render/*` split (post-refactor layout), the relationship between parsers and renderers, the `OpenXmlPackage` → `PresentationParser` → `Presentation` → `HtmlRenderer` pipeline.
  • Source Layout: annotated tree showing `src/.ts` (top-level) vs `src/render/` (16 files) with what each does.
  • Key Patterns: parser-to-model convention, renderer dispatch pattern, shape-geometry handling.
  • Test Conventions: Playwright-in-browser, `harness.html`, fixture placement.
  • Commands: npm script roster explained.
  • What NOT to do: don't switch to jest/vitest (browser-parity requirement), don't regress `any` count from ~3.
  • Common workflows: how to add a new shape preset, how to add a new parser field, how to close a conformance gap.
  • Important: anything load-bearing that isn't obvious.

Reference

See `/home/ben/code/python-docx/CLAUDE.md` or `/home/ben/code/docxjs/CLAUDE.md` as templates.

Surfaced by: 2026-05-05 consistency audit (item 6).

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

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions