Files
praxis/library/nodejs-project/SPEC.md
T
阿白叔andClaude Opus 4.7 17671b2b22 docs: add library/nodejs-project SOP with encoding checks
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 <noreply@anthropic.com>
2026-05-21 12:31:14 +08:00

7.6 KiB

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:

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

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:

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:

# 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

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

git add <specific files>           # NOT git add . / git add -A
git commit -m "<area>: <imperative summary under 60 chars>"
  • Always include Co-Authored-By: Claude <noreply@anthropic.com> (or the project's tool-specific trailer) for AI-assisted commits.
  • One topic per commit. "and" in summary → split.
  • English message.

Phase 7 — Push

git push origin <branch>
  • 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.

# 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]+' -- <changed-files>

# 3. Standard checks
npm run check
npm test

# 4. Commit + tag
git add <changed files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push origin <branch>
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: <list>. Sizes: <sizes>. Upload to <distribution
#    channel>?"

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. <area>: <imperative>.
[push]    main/dev/force? stop. else push.
[release] follow project's bump checklist. STOP before upload.