From 17671b2b2296129d212363c46ab137368a4b3671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=98=BF=E7=99=BD=E5=8F=94?= <11794527+absfan@user.noreply.gitee.com> Date: Thu, 21 May 2026 12:31:14 +0800 Subject: [PATCH] docs: add library/nodejs-project SOP with encoding checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 8-phase AI execution sequence for Node.js / Next.js projects: entry → frame → sync → edit → encoding → verify → commit → push → release. Phase 4 covers BOM / CRLF / non-UTF-8 detection and fixes — these are the most common silent corruption when AI edits files on Windows-default encoding systems. - library/nodejs-project/SPEC.md (new) - library/README.md catalog updated - AGENTS.md §5 Team library entry list updated Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 3 + library/README.md | 7 +- library/nodejs-project/SPEC.md | 238 +++++++++++++++++++++++++++++++++ 3 files changed, 245 insertions(+), 3 deletions(-) create mode 100644 library/nodejs-project/SPEC.md diff --git a/AGENTS.md b/AGENTS.md index ca290ec..fc19bb4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -530,6 +530,9 @@ Current entries: - [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit, what not to, how to recover from leaked secrets. +- [`library/nodejs-project/`](library/nodejs-project/SPEC.md) — task + execution SOP for Node.js / Next.js projects (entry → frame → sync → + edit → encoding → verify → commit → push → release). Promotion criteria, layout, and adding rules: see [`library/README.md`](library/README.md). diff --git a/library/README.md b/library/README.md index f1e8922..b3573fd 100644 --- a/library/README.md +++ b/library/README.md @@ -17,9 +17,10 @@ When starting a non-trivial task: ## Catalog -| Entry | Read it when… | -| -------------------------------------- | ---------------------------------------------------------- | -| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files | +| Entry | Read it when… | +| ------------------------------------------- | -------------------------------------------------------------- | +| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files | +| [`nodejs-project/`](nodejs-project/SPEC.md) | Working in any Node.js / Next.js project — task execution SOP | (More entries will be added as the team encounters recurring questions worth standardizing.) diff --git a/library/nodejs-project/SPEC.md b/library/nodejs-project/SPEC.md new file mode 100644 index 0000000..8b9c7d8 --- /dev/null +++ b/library/nodejs-project/SPEC.md @@ -0,0 +1,238 @@ +# nodejs-project — AI execution SOP + +## When to read this + +- Working in any Node.js / Next.js project (anything with a `package.json`). +- Initializing a new Node project. +- About to commit, push, or release a Node project. + +This is the AI's task-execution sequence. Each phase is a concrete set +of commands or checks the AI runs **on its own** before declaring the +task done. The only points that pause for the human are flagged +explicitly. + +## Phase 0 — Project entry + +Run on first action in the repo: + +```bash +ls AGENTS.md CLAUDE.md package.json .gitignore +node --version +cat package.json | grep -A 20 '"scripts"' +``` + +- **No `AGENTS.md`** → stop. Ask the human: "this project has no + AGENTS.md; create one before proceeding?" +- **No `.gitignore` or it's <100 bytes** → stop. The project is missing + basic ignore rules; flag before any commit. +- **`node --version` doesn't match what AGENTS.md says** → stop, ask. + +## Phase 1 — Task framing + +Trigger conditions, in order: + +- Task description < 3 sentences AND scope > 1 file → ask for the + 5-line spec (`Goal / Why / Done when / Out of scope / Risks`). +- Task touches: `package.json` deps, schema, auth, secrets, production + config, build scripts → confirm scope with human before any edit. +- Otherwise: write the implicit spec into the PR description draft and + proceed. + +## Phase 2 — Pre-edit sync + +```bash +git status # working tree clean? +git pull --ff-only # remote ahead? +``` + +- Working tree dirty with unrelated changes → stop, ask. +- `pull --ff-only` fails (diverged history) → stop, ask. Don't + force-pull, don't merge silently. + +## Phase 3 — Edit & verify + +After each meaningful change run: + +```bash +npm run check # if defined +npm test # if defined +npx tsc --noEmit # for TypeScript / Next.js +``` + +For projects with `build-release` or similar build scripts: do **not** +run them automatically — they produce large artifacts. Run only when +the task is "release." + +Failure handling: + +- Fix the error, re-run. +- **Same error twice** → stop, surface to human. Don't keep retrying. + +## Phase 4 — Encoding & line-ending checks + +Run before staging any text file changes. Source code on this team is +**UTF-8 without BOM**, line endings follow the project's existing +convention (typically LF, except `.bat` / `.cmd` which need CRLF). + +Detection commands: + +```bash +# Find files with UTF-8 BOM (EF BB BF) — should be empty output +git diff --cached --name-only -z | xargs -0 -I{} sh -c \ + 'head -c 3 "{}" | od -An -tx1 | grep -q "ef bb bf" && echo "BOM: {}"' + +# Find CRLF in source files that should be LF (skip .bat/.cmd) +git diff --cached --name-only -z | xargs -0 grep -lI $'\r' 2>/dev/null \ + | grep -vE '\.(bat|cmd)$' + +# Find non-UTF-8 bytes in source +git diff --cached --name-only -z | xargs -0 -I{} sh -c \ + 'iconv -f UTF-8 -t UTF-8 "{}" >/dev/null 2>&1 || echo "non-UTF8: {}"' +``` + +Hits → fix before commit: + +- BOM in `.js` / `.mjs` / `.json` / `.md` / `.html` / `.css` → strip. + Node `JSON.parse` rejects BOM in `package.json`. Some bundlers ship + BOM into the output and break browsers. +- CRLF in `.js` / `.mjs` / `.ts` / `.tsx` / `.json` / `.md` / `.sh` → + convert to LF. CRLF in `.sh` makes the script silently fail on Linux. +- CRLF in `.bat` / `.cmd` → keep, this is correct. +- Non-UTF-8 bytes (typically GBK on Windows) → re-save the file as + UTF-8 in the editor. This is the most common silent corruption when + AI edits a Chinese-content file on a system with Windows-default + encoding — symptom is "好" appearing as "濂" or similar mojibake. + +Editor / tool notes for the human: + +- Set editor to UTF-8 default and save without BOM. +- VSCode: status bar bottom-right shows current file's encoding; + click to "Save with Encoding → UTF-8" if needed. +- `.gitattributes` baseline (commit it once per project): + + ``` + * text=auto eol=lf + *.bat text eol=crlf + *.cmd text eol=crlf + *.png binary + *.jpg binary + *.zip binary + ``` + + This forces normalization on commit and prevents future drift. + +## Phase 5 — Pre-commit verification + +```bash +git status +git diff --cached +``` + +The AI must read the entire `--cached` diff and answer in its own +output: + +1. Build / typecheck pass? +2. Tests pass (or honestly: "didn't run because ")? +3. Files outside the stated scope? List + justify each, or revert. +4. New deps? List them in PR description and Phase 1 confirmation. +5. AI-generated comments restating the code? Delete. +6. End-to-end exercised (for user-visible changes)? + +Plus **Node-specific Phase 5 checks**: + +- `package-lock.json` in diff but no change to `package.json` deps → + stop. This is usually IDE auto-install. Revert the lockfile diff. +- `package.json` deps changed but no lockfile diff → stop. Run + `npm install` once, commit lockfile in same commit. +- `.env` / `.env.local` / `.env.production` / `*.pem` / `*.key` in diff + → **stop, do not commit**. Add to `.gitignore` if missing. +- `node_modules/` / `.next/` / `dist/` / `build/` / `out/` in diff → + stop. Gitignore is broken; fix before commit. +- Files >5 MB in diff (`git diff --cached --stat | awk '$3 > 5120'`) → + stop, ask human about LFS or out-of-band delivery. +- Any encoding hit from Phase 4 unresolved → stop. + +## Phase 6 — Commit + +```bash +git add # NOT git add . / git add -A +git commit -m ": " +``` + +- Always include `Co-Authored-By: Claude ` (or + the project's tool-specific trailer) for AI-assisted commits. +- One topic per commit. "and" in summary → split. +- English message. + +## Phase 7 — Push + +```bash +git push origin +``` + +- First push of a new feature branch: include `-u`. +- Branch is `main` or `dev` → **stop, ask human** before push. +- `--force` push → **stop, ask human**, regardless of branch. Quote the + reason and the branch back to the human. + +## Phase 8 — Release (product projects only) + +Only run when the task is explicitly "release vX.Y.Z." Skip otherwise. + +```bash +# 1. Read project's AGENTS.md "release-bump checklist" +# 2. For each listed file: edit, then verify no stale version remains +git grep -nE 'V?[0-9]+\.[0-9]+\.[0-9]+' -- + +# 3. Standard checks +npm run check +npm test + +# 4. Commit + tag +git add +git commit -m "chore: release vX.Y.Z" +git tag -a vX.Y.Z HEAD -m " VX.Y.Z" +git push origin +git push origin vX.Y.Z + +# 5. Build +npm run release # or project's build script + +# 6. List artifacts +ls -lh release/ # or wherever the build outputs + +# 7. STOP — ask human: +# "Artifacts ready: . Sizes: . Upload to ?" +``` + +The upload step is **always human-confirmed**. It's the only +externally-visible irreversible action in the flow. + +## Where the human pauses + +In total, AI stops and asks the human only at: + +- Phase 0: missing AGENTS.md +- Phase 1: vague task or scope-sensitive change +- Phase 2: dirty tree or diverged history +- Phase 3: same error twice +- Phase 4 / 5: encoding / lockfile / secret / large-file anomalies +- Phase 7: push to `main`/`dev` or `--force` +- Phase 8: distribution upload + +Everything else is self-running. + +## Quick reference (for AI to scan) + +``` +[entry] read AGENTS.md → no? stop. +[frame] vague task? → spec. scope-sensitive? → confirm. +[sync] git status / pull --ff-only. +[edit] npm run check / test / tsc. fail twice? stop. +[encode] no BOM / LF for src / CRLF for .bat / valid UTF-8. +[verify] git diff --cached → 6 questions + Node-specific 5. +[commit] git add by name. : . +[push] main/dev/force? stop. else push. +[release] follow project's bump checklist. STOP before upload. +```