From 17eb108e9b62551ba3d5cbb9227838598da571fb Mon Sep 17 00:00:00 2001 From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com> Date: Sun, 11 Oct 2026 08:40:46 +0000 Subject: [PATCH] docs(STRINGS-3714): add CLAUDE.md with spec workflow guidance Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..a31f1c984 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# strings-openapi + +## Spec changes workflow + +1. Before adding a path file or endpoint docs, grep `paths.yaml`, `doc/compiled.json` and `paths/` for the endpoint to confirm it is not already documented under another file name or tag. +2. Edit the source YAML. +3. Run `make lint` (runs `swagger-cli validate`, `make bundle`, then `lint.sh`). Do not run a second manual `swagger-cli bundle` afterwards. +4. `git diff` to confirm scope. +5. Commit the source change together with the regenerated `doc/compiled.json` (generated but committed). `tmp/compiled.yaml` is gitignored; never stage it. + +## Finding endpoints + +`paths.yaml` references path files, not literal URLs. Find where an endpoint is wired up with e.g. `grep -n "search.yaml" paths.yaml`. + +## Consistency + +When adding or editing a request-body property for a resource, apply it to both `paths//create.yaml` and `paths//update.yaml`, and to the shared response schema under `schemas/`, so POST/PATCH/GET contracts do not drift. + +## Breaking changes CI + +`.github/workflows/breaking-changes.yml` diffs the compiled spec against the base branch. Adding or reordering enum values, or altering shared response schemas such as `schemas/project_details.yaml`, can fail it. Inspect its diff output before pushing; if it fails on a purely additive enum/field change, explain the additive nature in the PR body instead of re-pushing the same change. + +## Commits and PR titles + +Use `docs(STRINGS-XXXX): ` for commit messages and PR titles (matches git log history), not the `JIRA-KEY - title` default.