writing

# writing — AI Reference

shimo4228/writing 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.

> **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/writing
- **Ecosystem hub**: https://github.com/shimo4228/shimo4228 (the author's hub: five practice lines this corpus reports from)
- **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
- **Status**: active and curated by hand; articles are added as they are published, and `docs/PUBLICATIONS.md` is generated, never hand-edited
- **Toolchain**: Zenn CLI 0.4.5, Python 3.13 run through uv, 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
- **Project skills**: `.claude/skills/` — `zenn-format`, `publish-article`, `substack-publishing`, and `article-stocktake`. `writing-ecosystem`, `quality-gate`, `session-theme-mining`, and `note-publishing` are project-local too.
- **Project agents**: `.claude/agents/` — `editor`, `essay-reviewer`, `prose-clarity-reviewer`, `fact-checker`, `devto-translator` (article drafting is done directly by the orchestrator, not delegated to a subagent)
- **Global writing assets**: `collect-context`, `headline-craft`, and `prose-translation` (in `~/.claude/skills/`)
- **Project rules**: `.claude/rules/writing-principles.md` holds the writing backbone (the author's principles); `.claude/rules/publishing-channels.md` 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. `note/` also holds verbatim note reposts of Zenn articles, whose canonical stays in `articles/`. 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**: at least one Zenn article per week (a floor, author decision 2026-10-22; previously 2–3 per week; Tuesday–Wednesday 07:00–09:00 JST preferred)
- **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 practice 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.

| Practice 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/affaan-m/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 | 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 shimo4228/writing?

shimo4228/writing 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 shimo4228/writing?

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 project-local `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 auditing them with a cold read isolated from the body. 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 project-local `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 `collect-context` → approved one-thesis editorial brief → orchestrator draft → (Zenn only) persona-read loop with skill `persona-read-loop` → 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 and cold-read audit → author title selection → project-local `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, `note-publishing` handles note, and `substack-publishing` handles 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 shimo4228/writing, 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 project-local `writing-ecosystem`.

## What Claude Code skills power the writing workflow?

The sole human-prose orchestrator is project-local `writing-ecosystem`. Theme discovery uses `session-theme-mining`; evidence collection uses `collect-context`; title generation and review are done by `headline-craft`; review uses the project agents in `.claude/agents/`; `quality-gate` aggregates the local contract. `writing-ecosystem`, `quality-gate`, and `session-theme-mining` are project-local alongside Zenn format, platform publishing (`publish-article`, `note-publishing`, `substack-publishing`), and reception measurement (`article-stocktake`). 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 at least one Zenn article per week (a floor, set on 2026-10-22; it was 2–3 per week from March 2026), not daily. The 2–3 per week 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.