Blog repository workflow

Start with repository truth

1. Read CLAUDE.md before changing content or code. Treat it as the authoritative project guide.
2. Inspect the current branch, remote state, and working tree before editing. Preserve unrelated local changes.
3. Read the files that own the behavior before proposing a change.

Route the task

• For a brief-driven article, read _briefs/README.md and docs/blog-editorial-workflow.md, then use .claude/skills/write-blog-from-brief/SKILL.md. Trace recurring source_refs across public briefs and article receipts before drafting; never dereference brain://.
• For a new or rewritten opening, also use .claude/skills/craft-article-opening/SKILL.md.
• For an approved English translation or presentation polish in either language, use .claude/skills/translate-and-format-blog/SKILL.md.
• For template or design work, trace the relevant layout, partials, Hugo resources, and extended CSS before editing.
• For taxonomy, metadata, or SEO work, inspect the project scripts and config/tags-mapping.json before changing content.

Preserve content invariants

• Store ordinary posts only under content/{lang}/{ai-agent|engineering|growth}/posts/.
• Store project pages only under content/{lang}/projects/.
• Use articles as the aggregate entry point.
• Use Shanghai timestamps with an explicit +08:00 offset and avoid future publish dates unless requested.
• Do not add draft to files in content/; keep unfinished work on an unmerged branch.
• Keep descriptions as plain text and use canonical tags from config/tags-mapping.json.
• Do not reintroduce the retired categories taxonomy.
• Put directly referenced article images in static/; reserve assets/ for Hugo Pipes.
• Cite factual external claims next to the supported sentence and end every researched article with ## 参考资料 or ## References. List each cited public source once with a descriptive link; do not add decorative or uncited sources.

Implement with the existing architecture

• Prefer repository-native Hugo layouts, partials, assets, and scripts over parallel implementations.
• Keep bilingual routes and labels aligned.
• Preserve responsive behavior, dark mode, accessibility, SEO metadata, and resource fingerprinting.
• Use apply_patch for intentional file edits and explicit paths when staging mixed worktrees.

Validate proportionally

Choose the lowest-cost validation layer that covers the changed surface.

For a standard article-only change using existing Markdown, front matter, routes, and cover conventions:

• inspect the changed document directly;
• run npm run frontmatter:check, npm run tags:check, and git diff --check;
• run npm run flavor:check for the changed Chinese Markdown set; it expands to --changed --check, includes staged, unstaged, and untracked files under content/zh, and fails on E-level errors. Do not substitute npm run flavor:scan, which scans the full Chinese corpus without check mode;
• verify the path, Shanghai timestamp, description, canonical tags, headings, inline citations, final reference section, internal links, and referenced asset paths;
• check both documents when the article is bilingual;
• do not launch a browser, take screenshots, run npm test, or run a full local production build by default.

Escalate only when the article introduces raw HTML, shortcodes, a new content type or route, unusual media, generated markup, or another rendering risk.

For template, CSS, JavaScript, configuration, or shared rendering changes:

• run only the relevant targeted tests and npm run typecheck when TypeScript changes;
• run hugo --minify when build behavior, templates, shortcodes, routes, or configuration change;
• use netlify dev and inspect the affected viewport and console only when rendering could have changed;
• use screenshots only when a visual baseline or before/after comparison materially helps; screenshots are not a default gate.

Leave the full Hugo build, full npm test suite, and cross-site visual regression to CI/CD. Repeat them locally only when CI is unavailable, the user requests it, a cross-cutting release is unusually risky, or a CI failure needs diagnosis. Wait for required CI checks before merging.

Deliver through GitHub

• Update from the remote before starting when the working tree allows it.
• Commit only the intended scope with a concise, contextual message.
• Prefer gh for GitHub operations.
• Follow the issue-closing rules in CLAUDE.md when a PR is associated with an issue.