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>
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
.gitignoreor it's <100 bytes → stop. The project is missing basic ignore rules; flag before any commit. node --versiondoesn'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.jsondeps, 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-onlyfails (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. NodeJSON.parserejects BOM inpackage.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.shmakes 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.
-
.gitattributesbaseline (commit it once per project):* text=auto eol=lf *.bat text eol=crlf *.cmd text eol=crlf *.png binary *.jpg binary *.zip binaryThis 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:
- Build / typecheck pass?
- Tests pass (or honestly: "didn't run because ")?
- Files outside the stated scope? List + justify each, or revert.
- New deps? List them in PR description and Phase 1 confirmation.
- AI-generated comments restating the code? Delete.
- End-to-end exercised (for user-visible changes)?
Plus Node-specific Phase 5 checks:
package-lock.jsonin diff but no change topackage.jsondeps → stop. This is usually IDE auto-install. Revert the lockfile diff.package.jsondeps changed but no lockfile diff → stop. Runnpm installonce, commit lockfile in same commit..env/.env.local/.env.production/*.pem/*.keyin diff → stop, do not commit. Add to.gitignoreif 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
mainordev→ stop, ask human before push. --forcepush → 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/devor--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.