Skip to content

CLAUDE.md

Latest commit

 

History

History
131 lines (99 loc) · 4.69 KB

CLAUDE.md

File metadata and controls

131 lines (99 loc) · 4.69 KB

Claude Code Instructions for zenn-content

Project Overview

This repository contains Zenn articles and books for AI agent development, Claude Code workflows, and LLM engineering experiments. All content follows the "Build in Public" principle, documenting real development sessions and design decisions.

Git Push Reminder (CRITICAL)

記事の作成・編集・schedule.json の更新をコミットしたら、必ずユーザーに push を促すこと。未 push のコミットがあると、Zenn の published_at 予約投稿が反映されず、Dev.to のクロスポストスクリプトも動かない。

Writing Guidelines

Zenn Article Format

All articles MUST use Zenn frontmatter:

---
title: "Article Title (50-60 characters)"
emoji: "📚"
type: "tech"  # or "idea"
topics: ["claude", "anki", "ai"]  # 1-5 tags
published: true  # or false for draft
published_at: 2026-04-15 07:00  # 予約投稿（JST、省略で即公開）
---

# Article content starts here

Content Standards

  1. Technical Depth

    • Explain "why" decisions were made, not just "what" was implemented
    • Include real code examples from the repository
    • Discuss trade-offs and alternatives considered

  2. Code Examples

    • All code snippets MUST be executable and tested
    • Include file paths for context (e.g., src/pdf2anki/quality.py:322-329)
    • Use syntax highlighting: ```python, ```typescript, ```bash
    • Add comments for clarity

  3. Terminology Consistency

    • Use consistent terms across articles:
      • "pdf2anki" (not "PDF2Anki" or "pdf-to-anki")
      • "Claude-Native" (design philosophy)
      • "CLI-First" (architecture principle)
      • "半自動 (Semi-automated)" (workflow approach)

  4. Tone and Style

    • Technical but approachable - Assume readers are engineers
    • Honest - Discuss failures and challenges, not just successes
    • Human insights - AI-assisted writing, but human perspective
    • No AI slop - Avoid generic phrases like "powerful tool", "revolutionize", "seamless"

  5. Structure

    • Introduction - Hook reader with a problem or insight
    • Context - Background and motivation
    • Implementation - Technical details with code examples
    • Lessons Learned - Reflections and takeaways
    • Conclusion - Summary and next steps

Image Guidelines

  • Store images in images/ directory
  • Use descriptive filenames: tokenization-flow.png not image1.png
  • Embed with Zenn syntax: ![Alt text](/images/filename.png)
  • Sanitize screenshots: no file paths like /Users/username/, no API keys

Editor Agent Usage

Before publishing, run review agents. For tech articles use editor, for idea articles use essay-reviewer. Run fact-checker in parallel to verify factual claims.

# tech 記事
claude --agent=editor --prompt="Review: articles/ARTICLE_NAME.md"
# idea 記事
claude --agent=essay-reviewer --prompt="Review: articles/ARTICLE_NAME.md"
# ファクトチェック（並列実行可）
claude --agent=fact-checker --prompt="Fact-check: articles/ARTICLE_NAME.md"

Available agents:

  • editor — tech 記事の構造・品質・AI slop 検出（4段階評価）
  • essay-reviewer — idea 記事の論理・トーン・過積載検出
  • fact-checker — 事実主張の Web 検索検証（ACCURATE/PARTIALLY/INACCURATE/UNVERIFIABLE）
  • devto-translator — JP→EN 翻訳 + Dev.to タグ付け + 投稿
  • zenn-drafter — 記事執筆（分析→執筆→セルフレビュー）

zenn-writer Skill

Use the zenn-writer skill for article-specific guidance:

claude skill zenn-writer

This skill provides:

  • Zenn frontmatter templates
  • Article structure patterns
  • SEO best practices
  • Code embedding formats
  • Image embedding formats

Testing Workflow

See docs/RUNBOOK.md for the full testing and publishing workflow.

Publishing Checklist

Full procedure: docs/RUNBOOK.md

  • Code snippets have no API keys
  • Screenshots have no sensitive information (file paths, usernames)
  • File paths are anonymized
  • All code examples are tested and executable
  • Editor/essay-reviewer レビュー完了
  • fact-checker でファクトチェック完了（idea 記事は必須）
  • Lint passes (npm run lint)
  • Preview looks good (npm run preview)
  • published_at を設定（YYYY-MM-DD HH:MM 形式、JST）
  • English translation created in articles-en/
  • schedule.json updated with both Japanese and English entries
  • Cross-post target scheduled: Dev.to (English)

IMPORTANT: This repository is PUBLIC. Never commit:

  • Personal file paths (/Users/username/)
  • API keys or credentials
  • Sensitive screenshots