writing

# writing

> Japanese and English writing by Tatsuya Shimomoto (shimo4228) on coding agents — how they remember, fail, get reviewed, and stay accountable — plus idea essays and the papers that grew from them. Japanese originals on Zenn, English editions on Dev.to, essays on note (JP) and Substack (EN); the Markdown sources here are canonical. Writing, reviewing, translating, and publishing are done with Claude Code.

Status: active and curated by hand; articles are added as they are published, and `docs/PUBLICATIONS.md` is generated, never hand-edited.

## Core documentation

- [Full AI Reference](llms-full.txt): self-contained Q&A, glossary, and project facts for AI search engines and AI agents
- [README (English)](README.md): human landing page — what the corpus is, three curated reading paths, where everything is
- [README (Japanese)](README.ja.md): 日本語版ランディングページ（同じ骨格）
- [Contributor guide](CLAUDE.md): writing guidelines, frontmatter conventions, review workflow
- [Citation metadata](CITATION.cff): the essay corpus as a citeable artifact, with its intrinsic content-derived identifier (Software Heritage snapshot)
- [License](LICENSE): CC0 1.0 Universal public-domain dedication across all content

## Publications

The exhaustive, generated index of everything published from this repository — Zenn/Dev.to articles, note/Substack idea essays, deposited papers, and the research lines — lives in one file. Article titles and URLs are not repeated here.

- [Publications index](docs/PUBLICATIONS.md): every article (JP Zenn URL + EN Dev.to URL or EN source), idea essay (note JP / Substack EN), and paper (Zenodo concept DOI, SSRN mirror), newest first; generated from `articles/*.md` frontmatter, `scripts/schedule.json`, and `scripts/corpus.yml` by `scripts/generate_article_index.py`
- [README reading paths](README.md#choose-your-next-path): three curated entry routes (agent memory · review without endless work · reconstructable autonomous behavior), generated from `scripts/reading_paths.yml`
- [Zenn profile](https://zenn.dev/shimo4228): Japanese articles as published · [Dev.to profile](https://dev.to/shimo4228): English editions · [Substack](https://shimo4228.substack.com): English idea essays

## Idea essays (note / Substack)

Author-voiced idea essays outside the Zenn/Dev.to convention. Since 2026-08 the Japanese canonical is first published on note (`note/`), and its English edition on Substack (`substack/`); earlier essays were Substack-first. `note/` also holds verbatim note reposts of Zenn articles, whose canonical stays in `articles/`. Per-essay URLs are in the [Publications index](docs/PUBLICATIONS.md#idea-essays-note--substack).

## Publishing pipeline

- [devto_crosspost.py](scripts/devto_crosspost.py): single-file per-article Dev.to cross-poster. `schedule <slug> --at "<datetime [Tz]>"` arms a one-shot launchd job at that time; it posts, records the URL, and self-removes. Subcommands: schedule / post / list / unschedule
- [schedule.json](scripts/schedule.json): posted-URL ledger for EN articles (the post time is a `--at` argument, not stored here)
- [generate_article_index.py](scripts/generate_article_index.py): renders `docs/PUBLICATIONS.md` and the README reading-path blocks from frontmatter + `schedule.json` + `corpus.yml` + `reading_paths.yml`; `--check` runs in CI and fails on drift (no bot commits)
- [corpus.yml](scripts/corpus.yml): hand-maintained membership for essays (note/Substack URLs), papers (DOIs), and research lines — the only inputs with no frontmatter to parse

Zenn (JP) publishing is not scripted — it uses Zenn's native `published_at` frontmatter scheduling.

## Claude Code integration

- [Publication channel contract](.claude/rules/publishing-channels.md): Zenn / Dev.to / note / Substack path, audience, register, review panel, validation, title constraints, and publish handoff
- [Project skills](.claude/skills/): the writing orchestrator `writing-ecosystem`, the acceptance gate `quality-gate`, theme discovery `session-theme-mining`, platform format and publishing (`zenn-format`, `publish-article`, `note-publishing`, `substack-publishing`), plus local reception measurement (`article-stocktake`)
- [Project agents](.claude/agents/): review agents `editor`, `essay-reviewer`, `prose-clarity-reviewer`, and `fact-checker`, all resident in this repository
- [.claude/agents/devto-translator.md](.claude/agents/devto-translator.md): JP→EN translation and Dev.to-specific draft preparation; publishing is a separate gated step
- [.claude/refs/schedule-schema.md](.claude/refs/schedule-schema.md): schedule.json schema

## 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. Attribution is carried by this federated-identifier layer, not by a license clause; the corpus is released under CC0-1.0.

- [Ecosystem hub](https://github.com/shimo4228/shimo4228): the author's hub: five practice lines and their DOIs (federation parent)
- [Author ORCID](https://orcid.org/0009-0002-6168-4162): persistent author identifier
- [CITATION.cff](CITATION.cff): citation metadata recording the corpus's intrinsic content-derived identifier (Software Heritage snapshot), the essay genre's priority-claim mechanism
- [Authorship Strategy (DOI)](https://doi.org/10.5281/zenodo.20263316): sibling line whose genre-split placement model governs this corpus's identifier and license
- [Agent Knowledge Cycle (DOI)](https://doi.org/10.5281/zenodo.19200726): sibling practice line
- [Contemplative Agent (DOI)](https://doi.org/10.5281/zenodo.19212118): sibling practice line
- [Agent Attribution Practice (DOI)](https://doi.org/10.5281/zenodo.19652013): sibling practice line
- [Attention, Not Self (DOI)](https://doi.org/10.5281/zenodo.20262112): sibling practice line

## Related

- [Zenn profile](https://zenn.dev/shimo4228): Japanese publication destination
- [Dev.to profile](https://dev.to/shimo4228): English publication destination
- [llmstxt.org](https://llmstxt.org/): the Answer.AI llms.txt standard this file follows