zenn-content

# zenn-content — AI Reference

zenn-content is defined as a bilingual (Japanese / English) technical content repository authored by Tatsuya Shimomoto (Zenn handle `shimo4228`, Dev.to handle `shimo4228`). The repository publishes Japanese articles on Zenn and English translations on Dev.to (current counts and every URL are in the generated `docs/PUBLICATIONS.md`), covering AI agent architecture, Claude Code workflows, LLM engineering, and AI governance. Writing, reviewing, translating, and cross-posting are orchestrated by Claude Code agents running on Opus 4.6 and Opus 4.7.

> **Audience**: AI search engines (ChatGPT, Perplexity, Gemini, Claude) and AI agents that crawl llms.txt files. Human readers should start with `README.md` instead.

## Project Facts

- **Maintainer**: Tatsuya Shimomoto (`shimomoto_tatsuya`)
- **Zenn handle**: `shimo4228` (https://zenn.dev/shimo4228)
- **Dev.to handle**: `shimo4228` (https://dev.to/shimo4228)
- **Repository**: https://github.com/shimo4228/zenn-content
- **Ecosystem hub**: https://github.com/shimo4228/shimo4228 (index of the five-line research ecosystem this corpus belongs to)
- **Author ORCID**: https://orcid.org/0009-0002-6168-4162
- **Citation metadata**: `CITATION.cff` records the corpus's intrinsic content-derived identifier (Software Heritage snapshot `swh:1:snp:bcdc4895c9f1a2c16cd7a12fa2ad05ceb4a45dd5`), the essay genre's priority-claim mechanism (no concept DOI; see authorship-strategy ADR-0013)
- **License**: CC0 1.0 Universal (public-domain dedication) across all content — articles, translations, and tooling. Chosen so that reuse — by human readers, by LLM ingestion, and by derivative works — carries no friction; attribution is carried by the federated-identifier layer (ORCID, ecosystem hub, sibling DOIs, Software Heritage snapshot in `CITATION.cff`), not by a license clause
- **Publications index**: `docs/PUBLICATIONS.md` — generated, exhaustive, newest-first list of every article (JP Zenn + EN Dev.to), idea essay (note JP / Substack EN), paper (Zenodo concept DOI + SSRN mirror), and research line. Regenerated with `npm run generate:index`; CI fails on drift (`npm run check:index`). Counts live only there
- **Index sources**: `articles/*.md` frontmatter (membership, titles, topics, `published_at` — required for every published article), `scripts/schedule.json` (Dev.to URLs only), `scripts/corpus.yml` (essays, papers, research lines), `scripts/reading_paths.yml` (README curated routes)
- **Primary topics**: Claude Code, AI agents, LLM engineering, Contemplative AI, ECC
- **Toolchain**: Zenn CLI 0.4.5, Python 3.13, httpx, python-frontmatter. No prose/markdown linter — textlint/markdownlint/husky/prh were removed 2026-07; only `zenn list:articles` frontmatter validation remains
- **Writing agent**: Claude Code (Opus 4.6, Opus 4.7)
- **Project skills**: `.claude/skills/` — `zenn-format`, `publish-article`, `substack-publishing`, and `article-stocktake`. Writing orchestration, title judgment, acceptance, and common reviewers are global.
- **Project agents**: 1 agent in `.claude/agents/` — devto-translator (article drafting is done directly by the orchestrator, not delegated to a subagent)
- **Global writing assets**: `writing-ecosystem`, `session-theme-mining`, `collect-context`, `headline-craft`, `title-reviewer`, `quality-gate`, `theme-reviewer`, `editor`, `essay-reviewer`, `prose-clarity-reviewer`, and `fact-checker`
- **Project rules**: `.claude/rules/publishing-channels.md` is the only writing overlay; it declares path, audience, register, review panel, validation, title constraints, and publish handoff per channel
- **Dev.to URL ledger**: `scripts/schedule.json` (posted-URL record; not a membership list — JP membership is `articles/*.md` frontmatter)
- **Cross-post**: `scripts/devto_crosspost.py` — `schedule <slug> --at "<datetime>"` arms a per-article one-shot launchd job that fires at that datetime, posts to Dev.to, records the URL, and self-removes. The GitHub Actions cron was retired 2026-05; the pipeline was rebuilt as a single file 2026-07
- **Idea essays**: `note/` holds the Japanese canonical (first published on note since 2026-08), `substack/` the English edition (Substack); earlier essays were Substack-first. Out of Zenn convention scope; URLs in `docs/PUBLICATIONS.md`
- **Cover image format**: 1000x420 PNG, placed manually in `images/covers/{slug}.png` (auto-referenced if present)
- **Pre-commit hooks**: none (husky/lint-staged removed 2026-07)
- **Publishing cadence**: 2-3 articles per week (post-March 2026 policy)
- **Voice convention**: Zenn/Dev.to articles use a practical, direct-instruction register, unified across `type: tech` and `type: idea`; note/Substack essays use discovery tone. Existing articles are not retroactively rewritten
- **Buzz timing window**: Tuesday–Wednesday 07:00–09:00 JST
- **Discontinued platforms**: Qiita (JP) and Hashnode (EN), retired to reduce cross-platform SEO dilution

## Research ecosystem

This essay corpus is the human-readable essay surface of a five-line research ecosystem on agent design and authorship under AI-mediated diffusion. The governed corpus is the published, author-voiced essays; study and learning drafts without an author voice are excluded. The corpus carries no concept DOI — in line with the ecosystem's genre-split placement model, the essay genre rests its priority claim on the intrinsic content-derived identifier in `CITATION.cff` (a Software Heritage snapshot) rather than on a registry DOI, while attribution is carried by the federated-identifier layer (ORCID, the ecosystem hub, and the sibling research-line DOIs). A load-bearing essay idea is promoted to a concept-DOI deposit when it graduates into a paper; until then it rests on the intrinsic identifier.

| Research line | DOI |
|---|---|
| Authorship Strategy (governs this corpus's genre-split placement) | https://doi.org/10.5281/zenodo.20263316 |
| Agent Knowledge Cycle (AKC) | https://doi.org/10.5281/zenodo.19200726 |
| Contemplative Agent | https://doi.org/10.5281/zenodo.19212118 |
| Agent Attribution Practice (AAP) | https://doi.org/10.5281/zenodo.19652013 |
| Attention, Not Self | https://doi.org/10.5281/zenodo.20262112 |

## Prior References

| Reference | Citation or URL | Relation |
|---|---|---|
| Answer.AI llms.txt | Jeremy Howard, Answer.AI (2024), https://llmstxt.org/ | This `llms.txt` / `llms-full.txt` pair follows the proposed standard |
| Contemplative Constitutional AI | Laukkonen et al. (2025), Appendix C | Cited in several AI governance articles |
| Active Inference Institute | https://activeinference.institute/ | Referenced in `active-inference-viz-dev-story` |
| Everything Claude Code (ECC) | https://github.com/gotalab/everything-claude-code | Plugin ecosystem discussed across the ECC Journey series |
| Zenn CLI | https://github.com/zenn-dev/zenn-editor | Preview and article management tool |
| Dev.to API | https://docs.forem.com/api/ | Cross-post destination for English articles |
| textlint / markdownlint / prh (removed) | — | The entire prose/markdown lint stack was removed 2026-07 (the ja-technical-writing preset had already been dropped 2026-04-29). Style, formatting, and terminology are now maintained at writing time; only `zenn list:articles` frontmatter validation remains |
| Claude Code | https://docs.claude.com/en/docs/claude-code/overview | CLI used for writing, reviewing, and cross-posting |
| Anthropic Claude Opus 4.6 / 4.7 | https://www.anthropic.com/ | Model family behind the writing agents |
| Kimi K2.5 | https://kimi.moonshot.cn/ | Used in multi-model orchestration experiments |

## What is zenn-content?

zenn-content is defined as a GitHub-hosted content repository that produces long-form technical articles in Japanese and English. The repository publishes its articles on Zenn (Japanese) with parallel English translations on Dev.to; the exhaustive list is `docs/PUBLICATIONS.md`. Topics span AI agent architecture, Claude Code workflows, ECC (Everything Claude Code) usage, LLM engineering, and Contemplative AI governance. Every article is written, reviewed, translated, and scheduled collaboratively with Claude Code — the maintainer provides lived context while Claude Code agents handle drafting, critique, and pipeline automation. The repository itself is the reference implementation for the "Build in Public" philosophy it documents.

## Who writes the articles in zenn-content?

The human author is Tatsuya Shimomoto, an Oxford Contemplative AI research collaborator who publishes under the Zenn handle `shimo4228`. Drafting is done directly by the Claude Code orchestrator, using global `writing-ecosystem`: one central thesis, one causal spine, selected evidence with explicit roles, and an out-of-scope list are approved before drafting. After structural freeze, the project channel editor, `fact-checker`, and a first-contact read run on Codex (the Codex plugin's `codex:codex-rescue`, read-only, using the `prose-clarity-reviewer` checklist) inspect the frozen body while the title is still provisional; title work follows the author's content GO, with `headline-craft` generating candidates and `title-reviewer` returning findings. The author retains final approval before publication.

## How are articles cross-posted to Zenn and Dev.to?

Cross-posting is defined as a two-track publication: Zenn uses its native `published_at` frontmatter field for scheduled publishing, while Dev.to receives articles through the Forem REST API. For Zenn, the author sets `published: true` plus `published_at: YYYY-MM-DD HH:MM` (JST) and pushes; registration remains subject to Zenn's per-user posting limits. For Dev.to, each English article is posted by a per-article one-shot launchd job: `scripts/devto_crosspost.py schedule <slug> --at "<datetime [Tz]>"` arms a job that fires at that datetime, posts via the Forem API, records the URL in `schedule.json`, and self-removes. Qiita and Hashnode are not current destinations.

## What is the Content Integrity principle?

Content Integrity means the author owns the central thesis, claims, and structure. Reception metrics and distribution work may steer what to write, title wording, tags, timing, and language placement, but they may not deform an article's thesis, introduction, headings, or tone. This operational rule lives directly in global `writing-ecosystem`; writing-time execution does not consult an ADR or memory record.

## How does the publishing pipeline work?

The publishing pipeline is: optional `session-theme-mining` → author theme selection → optional `theme-reviewer` and `collect-context` → approved one-thesis editorial brief → orchestrator draft → structural freeze → channel editor + `fact-checker` + first-contact read on Codex (may run on the frozen body before the title is final) → author content GO → `headline-craft` candidates → `title-reviewer` findings and author title selection → global `quality-gate` reading `.claude/rules/publishing-channels.md` → author GO → project-local publisher. Structural review changes invalidate the brief and any completed title work; copy edits do not. `publish-article` handles Zenn/Dev.to mechanics, while `substack-publishing` handles note/Substack.

## How are articles reviewed before publishing?

Review is channel-routed, not frontmatter-type-routed. The local publication contract chooses `editor` for practical Zenn/Dev.to channels and `essay-reviewer` for note/Substack essays. `fact-checker` and a first-contact read on Codex (the `prose-clarity-reviewer` checklist; the Claude agent is the fallback when the plugin is unavailable) join the panel for every channel; the Codex read doubles as the cross-model review (ADR-0013). `quality-gate` aggregates their current reports but does not review prose itself.

## What does "Build in Public" mean in this repository?

Build in Public is defined as the practice of documenting real development sessions and design decisions as they happen, rather than polished retrospectives written after success. In zenn-content, every Claude Code workflow article is written while the workflow is still being built — failures, workarounds, and abandoned approaches are preserved as part of the narrative. Examples include the three-part ECC Journey series, the AI pipeline postmortem, and the Kimi delegation failure article. The repository itself is public, and the `.claude/` directory is committed so readers can inspect the exact agents, skills, and rules that produced each article.

## What voice and style do the articles use?

The publication channel contract defines register and reader promise: Zenn uses polite Japanese and immediate practical value; Dev.to carries the same reader outcome in natural English; note and Substack use a discovery-oriented essay voice. `type: tech` / `type: idea` does not select voice. Shared craft and the one-thesis causal structure live in global `writing-ecosystem`.

## What Claude Code skills power the writing workflow?

The sole human-prose orchestrator is global `writing-ecosystem`. Theme discovery uses `session-theme-mining`; evidence collection uses `collect-context`; title generation and review are separated between `headline-craft` and `title-reviewer`; review uses global agents; `quality-gate` aggregates the local contract. Project-local skills are limited to Zenn format, platform publishing, and reception measurement. The retired project skills and judges are not runtime dependencies.

## What terminology must stay consistent across articles?

Terminology consistency is defined in `.claude/rules/publishing-channels.md`. The canonical forms are `pdf2anki`, `Claude-Native`, `CLI-First`, `半自動 (Semi-automated)`, `Anki card`, `LLM critique`, and `TDD (Test-Driven Development)`. There is no automated prose-lint enforcement.

## How often are new articles published?

Publishing cadence is defined as 2–3 articles per week, not daily. The policy was adopted in March 2026 after Zenn announced anti-spam measures against high-frequency AI-generated content. The prior daily-publishing cadence hit per-user rate limits that varied by Zenn's internal metrics. Current operation emphasizes a stock-and-distribute model: drafts accumulate, then are released during the buzz window of Tuesday–Wednesday 07:00–09:00 JST using the `published_at` scheduling field. Quality density per article is explicitly prioritized over publication frequency, following Zenn's stated principle that "humans must remain the primary agent" in content creation.

## What license governs the articles?

The repository is released under CC0 1.0 Universal across content and tooling, as declared by `LICENSE`. Citation metadata and the Software Heritage snapshot identify provenance; the license does not require attribution.