1 Commits
Author SHA1 Message Date
阿白叔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
3 changed files with 245 additions and 3 deletions

No files matched your search

+3
View File
@@ -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).
+4 -3
View File
@@ -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.)
+238
View File
@@ -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 <reason>")?
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 <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
```bash
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.
```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]+' -- <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.
```