From 388374990b4baa5ee3b784fb9996378bc3090d97 Mon Sep 17 00:00:00 2001 From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com> Date: Thu, 15 Oct 2026 19:48:40 +0000 Subject: [PATCH] docs(API): add CLAUDE.md with spec-authoring guidance from post-mortem Covers validate/bundle pipeline, PR title format, endpoint documentation rules, and checking for copy-pasted descriptions. Refs STRINGS-3797. Co-Authored-By: Junior (Claude Sonnet 5.5) --- CLAUDE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 2965dc3ab..b4d53748d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ 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. +6. `bash ./lint.sh` reads the gitignored `tmp/compiled.yaml`; `make lint` or `make bundle` generates it first. Do not treat a failure on a missing file as your own regression. For an additive change, check `git diff doc/compiled.json` is purely additive. ## Finding endpoints @@ -26,3 +27,15 @@ PR titles are used to generate client library changelogs and version bumps. Foll - `change_type`: `feat` (new endpoints, properties, query parameters), `fix` (schema fixes), `docs` (description-only changes, no schema change), `build` (build system or CI changes). - `affected_library`: most commonly `API`; schema changes always use `API`. +- The `Validate PR title` check (`.github/workflows/check-pr-title.yml`) enforces this prefix; compose the title correctly on the first push. Use `fix(API):` for corrections to an existing spec (missing params, wrong fields) rather than `feat(API):`. + +## Documenting endpoints + +- Never infer response attributes from sibling endpoints or plausibility. Derive them from the live API (e.g. `curl -s https://api.phrase.com/v2/`) or the actual serializer. For any field or query parameter you could not verify that way, say so in the PR body as inferred, not confirmed. +- Name tags and summaries the way TMS already names the same concept (e.g. tag `Supported Languages`, summary `List supported languages`). +- Keep endpoint descriptions limited to authentication requirements; do not document rate limiting or other operational behaviour that may change. +- If an endpoint's response shape or behaviour changes depending on query params, or two paths (e.g. `/accounts/.../members` vs `/projects/.../members`) use different serializers, do not document a single merged shape. Keep the schemas separate and flag the ambiguity in the PR body for a human decision. + +## Copy-pasted descriptions + +Before editing a description, field doc, or parameter block, run one repo-wide Grep for the same phrasing/field across `paths/` and `schemas/`; these are routinely copy-pasted across sibling endpoints. Fix every occurrence in the same PR or list the ones deliberately left alone in the PR body.