blog

# 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`. - When a passage could benefit from an interactive explanation or instructional animation, apply the selection guidance below and read [the component author guide](../../../docs/interactive-articles.md) before choosing a renderer. - 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. ## Interactive explanations and animation During planning, writing, or presentation review, proactively consider whether readers would understand a claim better by changing a condition, comparing outcomes, or stepping through state changes. When that teaching benefit exists, prefer the repository's **native Web Components + `interactive` shortcode + build-time data** approach. The author need not explicitly ask for animation each time; preserve the task's content and publication authorization. - Start with the question the reader should answer and the variable or state they can inspect. Place the figure beside the passage it explains, with a default result, a small set of controls, an interpretation, and explicit assumptions/sources. - Reuse an existing kind only when its semantics fit: `context-budget` models capacity allocation and overflow; `agent-loop` replays authored Agent/tool events and stop reasons. Add an instance through `data/interactive/<spec>.json` and a page-unique shortcode ID, without changing runtime code. - For session projections, identity grouping, memory lineage, recovery, GitOps, numerical tradeoffs, vectors or flow bottlenecks, consult the author guide's **Choose a teaching model** table and the linked kind reference before introducing a new component. Keep the model's assumptions and undefined/unknown states visible. - For a different teaching model, inspect existing renderers first. If new behavior is needed within the task's scope, extend the reviewed component registry, schema, static rendering, and tests together. Do not force an unrelated process into Agent-event fields or create a one-off inline script, framework app, or external embed for each article. - Motion should explain order, causality, or a state change. Start still, expose the controls the explanation needs (for example step/play/pause/reset), honor reduced motion, and retain keyboard/touch operation. Prefer an interactive figure over a GIF/video when readers need to control variables or inspect intermediate states; use actual footage when the point is to show a real interface or observed behavior. - Keep structural relationships in a static diagram when that is clearer, and keep ordinary prose when interaction adds no insight. Preserve working legacy `demo-*` uses unless the task calls for migration; this preference is not a site-wide rewrite. - Follow the author guide's shared-data static fallback, print, bilingual copy, scoped styles, and per-page resource rules. Reader interaction remains local and transient: no new backend, model calls, persistence, or third-party runtime. Label illustrative numbers and preset traces honestly; they do not measure real model quality or reveal private reasoning. Keep the field vocabulary, examples, limits, and detailed acceptance commands in [the author guide](../../../docs/interactive-articles.md) and [acceptance reference](../../../docs/interactive-articles-acceptance.md), rather than duplicating the schema in this skill. For data/shortcode additions run `npm run interactive:check` and inspect the affected localized pages; for shared component behavior changes also run `npm run interactive:test`. Add manual checks for the changed surface and report unrun checks honestly. ## Validate proportionally Choose the lowest-cost validation layer that covers the changed surface. For skill or workflow documentation only, validate skill metadata, linked paths, routing consistency, and `git diff --check`; a site build or browser run is unnecessary unless rendered content or code also changes. 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.