yaakai.to

docs を管理する Skill を作って (A)DR + 数個の Markdown で開発をしている

Wed, 11 Mar 2026 00:00:00 GMT

最近 ADR を使った開発に関する話題をよく見かける気がするが、自分も前に記事を書いたときから ADR 中心の開発を続けていて、その型が自分の中で固まってきたので現時点でのものをまとめる。

仕様駆動開発風のオレオレ実装計画を作って AI と併走する - yaakai.to

🐧 仕様駆動開発風のオレオレ実装計画を作って AI と併走する | yaakai.to

yaakai.to

先に断っておくと基本的には個人の private なリポジトリで使っているものなので実際の出力のサンプルはない。

概要としては以下のような感じで、これで分かる人は見なくていい内容だと思う:

docs/adr もしくは docs/decisions に意思決定ログとして (A)DR を書き、それを元に Plan などを作成して開発
AI 向けのドキュメントは基本 (A)DR + CLAUDE.md のみ
人間向けのドキュメントとして (A)DR がすべて反映された ARCHITECTURE.md と README.md を作成する Skill を用意して作成
(A)DR を書くために AskUserQuestion や WebSearch を使う Skill を別途用意

(A)DR と書いているのは、技術要素や Architecture っぽいものでなくとも Decision Record として残すようにしているため。以後は ADR とする。

ツッコミ回避をしておくと、リポジトリに人間用のドキュメントを入れる必要はないし、毎回 AI に聞いてコードベースと ADR を調べてもらえば良い、というのはそれはそうだと思っている。 ARCHITECTURE.md はほぼ趣味九割であるといい感じに見えるという理由で入れている。一割の実用は AI をあらゆるドキュメントの代わりに使うにはまだ速度が足りないのと、AI が 100% 生成しているわけではないので人間目線で出力がある程度読みやすいからという感じ。

ディレクトリ

/
├── .claude
│   └── skills
│       └── doc-writer/SKILL.md
├── docs
│   ├── decisions
│   │   ├── 2026-02-26-foo-foo-foo.md
│   │   ├── 2026-02-28-bar-bar-bar.md
│   │   └── 2026-03-02-buzz-buzz-buzz.md
│   ├── ARCHITECTURE.md
│   └── FOOFOO.md
├── CLAUDE.md
├── README.md
└── YAAKAITO.md

よくある感じ。

ARCHITECTURE.md 以外にも人間向けのドキュメントを残していることがたまにある。大体は調べたこと + あとで反映したいことを一時的にまとめるために使っていて、Issue にしたりコードに全部反映したら消している。

YAAKAITO.md は完全に自分用のメモで global に gitignore されたものを置いている。リポジトリに入れるなという話はあるが、 DevContainer を使っている関係でここが一番扱いやすい、中身は自由なメモ。

ADR と ARCHITECTURE.md を書くための Skill

2 つのフォーマットと、常にコードベース > ADR > ARCHITECTURE.md であることを知識として Skill にしている。フォーマットや構造はリポジトリ毎に微調整したいことがあるので Plugin なんかではなくリポジトリに commit している。

---
name: doc-writer
description: Write or update project documentation (Decision Records and ARCHITECTURE.md). Use when requests involve "create DR", "create ADR", "record decision", "write ARCHITECTURE.md", "update architecture doc", "document design decisions", or equivalent requests to summarize prior discussion into a decision record. Also triggers on requests to summarize architecture, reflect decision changes into documentation, describe the overall project structure, or when code changes warrant updating architectural documentation. Use this skill even when the user doesn't explicitly mention "DR" or "ARCHITECTURE.md" — any request about recording why a technical choice was made or capturing the current system design should use this skill.
user-invocable: true
---

# Document Writer

Create Decision Records (DR) and update ARCHITECTURE.md. DR is essentially synonymous with ADR (Architecture Decision Record) — no distinction is made.

## Document Map

```
CLAUDE.md                    -- Architecture Overview, Core Principles
docs/ARCHITECTURE.md         -- Detailed architecture document
docs/decisions/
  yyyy-mm-dd-slug.md         -- Decision Records (DR)
```

- Keep `CLAUDE.md` Architecture Overview and Core Principles consistent with ARCHITECTURE.md

## Routing

Execute one of the following based on the request:

1. **Create/edit a DR** → Follow the "Decision Record Writing" section
2. **Create/update ARCHITECTURE.md** → Follow the "Architecture Document Writing" section

## Decision Record Writing

### Naming

- Filename: `yyyy-mm-dd-slug.md` (date is the creation date)
- Location: `docs/decisions/`

### Title

Use `# Title` format. Preserve existing `# ADR NNNN:` titles as historical records.

### Template

When creating a new DR, read `references/decision-record-template.md` with the Read tool and follow its structure.

### Writing Guidelines

- Context and Decision are written by the user. Only the user can accurately describe their decision-making context and judgment — ask for these sections' content and compose the DR from their answers
- Write Decision in active voice with "We will ..." statements
- Consequences should cover positive, negative, and neutral outcomes — a consequence often becomes Context for a future DR
- Cross-link related existing DRs in the Notes section
- Write section headings in English (Status, Context, Decision, Consequences, Notes)

## Architecture Document Writing

ARCHITECTURE.md is a document written for humans, not AI agents (CLAUDE.md serves that role):

- Helps new developers and maintainers understand the system's design intent without reading every source file
- Documents core architectural concepts that reviewers rely on when evaluating whether a change aligns with the system's design direction

Analyze DRs and the codebase to create or update ARCHITECTURE.md.

### Instructions

1. Examine the package structure under `packages/`, package.json dependencies, and main entry points
2. Examine `.github/workflows/` to understand where and how each package runs
3. Read all DRs under `docs/decisions/`
4. Create or update ARCHITECTURE.md following the guidelines below

### Source Priority

Follow **codebase > DR > existing ARCHITECTURE.md** priority. Code is the single source of truth — DRs record intent but implementation may lag behind, so trust sources in this order. If a DR is accepted but not yet reflected in code, describe the current code state. Only reflect DR content to the extent it is implemented in code.

### Updating

Broad but shallow coverage has no value — the user selects which items to focus on. Present proposed changes to the user and apply only after approval.

After updating ARCHITECTURE.md, check whether `CLAUDE.md` Architecture Overview and Core Principles need updates, and propose them if so.

### What to Include

Record the knowledge a human needs to understand this system — the design intent, the reasoning behind structural choices, and the mental model that makes the codebase navigable. A new developer reading ARCHITECTURE.md should come away understanding why the system is shaped this way, not just what exists.

- Text-based overview diagram (execution environments and data flow)
- Design principles and how they are concretized in each component
- Package collaboration structure and dependency rules centered on core types
- Where each package runs and how it connects to others
- Technology selection rationale (only when significant context exists, such as cost, constraints, or bug avoidance)

### Prohibited

- Direct code (command examples, schema definitions, function signatures, etc.). Sample JSON is allowed (see "Exceptions" below)
- Facts obvious from reading code (CLI flags, API endpoint lists, etc.) or enumerations of each package's implementation details
- Inventing names that don't exist in the codebase
- Describing historical changes ("originally X, then changed to Y"). Change history belongs in DRs — write only the current state and intent
- Meta-descriptions of the document's own purpose
- Operational details (schedule frequencies, CI/CD configuration values, etc.) — these change frequently and become stale

### Style

- Write declaratively, not in Q&A format. State the current state in each section with intent woven in naturally
- Keep it simple. Avoid verbose explanations
- Write for a human reader — use natural narrative flow, not bullet-point checklists optimized for machine parsing

### Examples

**Bad — stating what's obvious from code:**
cli-fetch-rss is a package that fetches RSS feeds, accepts a group argument,
loads a list of corresponding feed URLs, and fetches them in parallel.

**Good — design intent not readable from code:**
Feed fetching and AI processing are separated into different packages so that
expensive AI processing can be skipped for quick debugging.

**Bad — historical narrative:**
Originally called the Claude API directly, then migrated to Agent SDK.

**Good — current intent only:**
AI processing uses Agent SDK. By providing tools to agents, they can fetch
external information as needed to make decisions.

### Format

When creating or significantly revising ARCHITECTURE.md, read `references/architecture-template.md` with the Read tool and follow its structure. The format is inspired by [esbuild's architecture.md](https://github.com/evanw/esbuild/blob/main/docs/architecture.md).

- **Leading comment**: Always include an HTML comment at the very top of the file (before the table of contents) stating that this document is for human readers and directing AI agents to also read the Decision Records under `docs/decisions/`

  ```html
  <!--
    This document is written for human readers.
    If you are an AI agent, also read the Decision Records under docs/decisions/.
  -->
  ```
- **Table of contents**: Place a nested bulleted list below the leading comment (before the title). Each item is an anchor link to a section heading
- **Design principles**: Use `* **Principle Name**` + indented paragraph (not `**Name**: description` inline format)
- **Section headings**: Write in English
- **Overview diagram**: Text-based ASCII diagram. Do not use Japanese inside boxes (monospace fonts misalign). Do not include specific configuration values like cron frequencies

### Exceptions

The following are allowed as exceptions to the "don't write details" principle in Prohibited:

- ...

## User Prompt

$ARGUMENTS

ある程度複合的なことをする Skill になっているので、細かいものにわけてもいいと思う。知識の共有がだるかったのとそんな大した量でもないので一緒にしてしまっている。

一応英語に変換してもらっているが、ある程度はメンテすることを前提にしているので普段の会話で使っている言語でいいと思う。

ADR

なにかしらの方法で議論しコンテキストが満たされている状態で、

/doc-writer ここまでの議論の内容を ADR としてまとめて

とかで作っている、フォーマットは Michael Nygard 氏の ADR に Notes 欄を足したものを使うことが多い。 ADR 自体は特に特殊なものでもなく、良い解説は世の中に溢れていると思うので割愛。

事前の議論の密度にもよるが、 Context と Decision はできるだけ監修するというか、ほとんど自分で書くようにしている。

ADR はすべての変更に対して作成しているわけではなく、技術要素の変更や人間がちゃんと確認して承認したいことを中心に書いている。意味が変わらない程度のちょっとした機能の改善、 UI の調整、リファクタリングやバグフィックスでは不要。

ARCHITECTURE.md

これは人間向けだから AI は ADR をちゃんと辿ってねと苦し紛れにコメントで書いている、多分大して意味はない。

ADR の実装が終わった後なんかに、

/doc-writer ARCHITECTURE.md に @docs/decisions/2026-xx-xx の内容を反映して

みたいな感じで一旦下書きをしてもらい、気に入らなかったら何度か会話して自分好みのものにしている。自分は esbuild の architecture.md の感じが好きなのでそれを目指して書いているが、細かいルールがあるわけではないので好きに書くのがいいと思う。

esbuild/docs/architecture.md at main · evanw/esbuild

An extremely fast bundler for the web. Contribute to evanw/esbuild development by creating an account on GitHub.

github.com

また、すべての ADR を反映しているわけではなく、その必要もないと思っている。反映の基準としては以下のどれかに当てはまると思ったら書き加えたり消したりしている:

人間がコードレビューをするときに、事前知識としてあったら嬉しい情報
しばらく触らないと忘れそうだが ADR を辿るのはだるそうな、なにかしらの意図がある情報
一度試したがあまりうまくいかなかったことと、その解決策

CLAUDE.md

Architecture Overview として概要を書くことが多くて、ARCHITECTURE.md からさらに厳選した以下のようなものを 2-3 行書いている。

複数の環境で動くいくつかのパッケージがある場合は、その関係性とデータの流れ
複数のパッケージでなにかしら統一したい方針があるならそれ
キャッシュ使って無駄に API にリクエストしないでねみたいな勘所

他はよく言われている内容で、最小限に AI が知らない固有のことだけを書くように努力している。

README.md

人間向けの手順とか書く。AI 以前から特に変わってない。

周辺

`/discuss` Skill

以前は全体の流れに含んでいたが、独立して議論モードに入るための Skill として用意している。

---
name: discuss
description: Structured discussion to explore design approaches and reach decisions. Analyzes the codebase, researches best practices, and clarifies requirements.
user-invocable: true
disable-model-invocation: true
---

# Discuss

You are the user's peer engineer in a design discussion.
Your role is to help the user reach a well-informed decision — not to give answers, but to ask the right questions, surface relevant context, and lay out trade-offs so the user can decide with confidence.

## Core Rule: Use AskUserQuestion for All Questions

When you need input from the user, always use the **AskUserQuestion tool** — never embed questions as plain text in your response. This keeps the discussion interactive and structured. Text output is for sharing analysis, context, trade-offs, and summaries — not for asking questions.

If you have both analysis to share and a question to ask, share the analysis as text and then call AskUserQuestion in the same turn.

## Purpose

- Clarify and organize ideas
- Identify requirements
- Explore design approaches

## Behavior

### Adaptive Discussion

During the conversation, use the following approaches as needed:

1. **Explore** - When technical context is needed:
   - Use **Glob** and **Grep** to find related code, existing patterns, and tech stack
   - Use **Read** to examine architectural decisions (ADRs, CLAUDE.md, README)
   - Use the **Explore agent** for broad codebase investigation that requires multiple queries

2. **Clarify** - When requirements are ambiguous:
   - Use **AskUserQuestion** with 2-4 concrete options per question
   - Cover key categories: Scope, Behavior, Data, Users, Integration, Constraints, Priority, Edge cases
   - Skip questions answerable from codebase analysis
   - Combine multiple related questions into a single AskUserQuestion call (up to 4 questions per call) rather than asking one at a time

3. **Research** - When external guidance would help:
   - Use **WebSearch** to find best practices — cross-reference multiple sources to avoid relying on a single opinion or outdated information
   - Prioritize official documentation over blog posts and community answers
   - Present findings with applicability assessment for the user's specific context

### Key Principles

- Listen actively and provide constructive feedback
- Present options with pros/cons when decisions are needed
- Summarize key points periodically
- When the user asks to "clarify", "dig deeper", or explore further, respond by using **Clarify** or **Research** to continue the discussion
- Do NOT create code or documentation unless explicitly requested

## Output

When the discussion reaches a natural conclusion, provide a summary using this template:

## Discussion Summary
### Decisions
- [What was decided and why]

### Open Questions
- [Unresolved items that need further investigation or input]

これは User レベルの Skill として用意していてリポジトリには依存しないものとしている。大体は新しいセッションを起動してこの Skill ではじめる。

/discuss foo をしたい、bar は buzz で bunbun

コードを書かないモードになっていて、都度 AskUserQuestion で必要な情報を聞いてくれる。さらに深堀りが必要そうなときは繰り返して満足行くところまでやっている。満足したら /doc-writer に任せる。

これは以下のものを参考にさせてもらっていて、影響を強く受けている:

JavaScript is not available.

x.com

claude-code/dig/commands/dig.md at master · fumiya-kume/claude-code

Kuu's Claude Code utils for myself. Contribute to fumiya-kume/claude-code development by creating an account on GitHub.

github.com

要件定義を行うための、Claude Code用カスタムスラッシュコマンド

要件定義を行うための、Claude Code用カスタムスラッシュコマンド. GitHub Gist: instantly share code, notes, and snippets.

gist.github.com

Claude Code on the web

ADR を作った時点で一度コンテキストが切れる(ことができる)ので、ローカルで ADR だけ作って実装は on the web でやってみたり、その逆をしたりしている。複数の worktree を監視するのは面倒だが、 on the web であれば結構気楽に複数タスクを投げれるようになってきたので便利。

ただ、on the web で /discuss で会話を始めるのがうまくいかなくて、Skill として登録なんかはしているのだが動いている感じがしない。なので on the web で ADR を作る場合は入力が増えがちかもしれない。

ADR の実装

ほぼほぼ Plan Mode に ADR を食わせるだけでやっている。フェーズがいくつかある場合は、大まかなタスクリストを Markdown として作って、ADR と合わせて渡してフェーズごとに Plan Mode → 実装とすることもある。

GitHub Agentic Workflows

まだお試しレベルだが、ADR 以外のドキュメント類で間違っている部分を GHA で検出するのを試している。以下の記事に書いたものと同じ:

GitHub Agentic Workflows を使ってみる - yaakai.to

🚜 GitHub Agentic Workflows を使ってみる | yaakai.to

yaakai.to

---
description: Validate ARCHITECTURE.md and CLAUDE.md for factual accuracy against the current codebase
on:
  schedule: weekly
  workflow_dispatch:
permissions:
  contents: read
  issues: read
  pull-requests: read
engine:
  id: copilot
  model: gpt-5
tools:
  github:
    toolsets: [default]
  edit:
safe-outputs:
  github-token: ${{ secrets.AI_USER_GH_TOKEN }}
  create-pull-request:
    max: 1
    labels: [documentation, ai-automate:claude]
  add-labels:
    allowed: [documentation, ai-automate:claude]
---

# Validate Documentation

You are an AI agent that validates ARCHITECTURE.md and CLAUDE.md for factual accuracy against the current codebase.

### Scope

Only check for **incorrect** items. Do NOT:
- Add missing items or sections
- Remove items that are correct
- Suggest improvements or reorganization
- Change style or wording unless factually wrong

An item is "incorrect" when it describes something that contradicts the actual codebase — for example, a package name that doesn't exist, a wrong file path, a description that doesn't match what the code actually does, or a stated principle that the codebase explicitly violates.

### Steps

1. Read `.claude/skills/doc-writer/SKILL.md` to understand the documentation rules and structure
2. Read `.github/scan/validate-docs.md` — this is the suppression list. Any documentation item listed there is an intentional decision and must be skipped entirely. Do NOT flag, modify, or mention suppressed items.
3. Examine the package structure under `packages/` (list directories, read package.json files and main entry points)
4. Examine `.github/workflows/` to understand where and how each package runs
5. Read `docs/ARCHITECTURE.md` and validate every factual claim against the codebase
6. Read `CLAUDE.md` and validate every factual claim against the codebase
7. If no incorrect items are found, call `noop` with "Documentation is accurate. No fixes needed." and stop
8. If incorrect items are found:
   a. Fix only the incorrect items in ARCHITECTURE.md and/or CLAUDE.md using the edit tool
   b. Use the `create-pull-request` safe output with:
      - Branch name: `chore/fix-docs-YYYYMMDD-RUNID` (where YYYYMMDD is today's date and RUNID is the current GitHub Actions run ID)
      - Commit message: `docs: fix incorrect items in ARCHITECTURE.md / CLAUDE.md`
      - Title: `docs: fix incorrect items in project documentation`
      - Body listing each incorrect item found and what was fixed

## Language Policy

Write commit messages, PR title, and PR body in the same language as README.md.

### Output

- If no incorrect items are found (the expected common case), call `noop` and stop. Do NOT create a PR.
- If clear factual errors are found, use the `create-pull-request` safe output to submit a PR with the fixes. Never push directly to the branch.

まだあまり運用はできていないが、ちょっとしたことでも割と見つけてくれる感じで便利。週 1 くらいで動かすようにしている。

雑感

リポジトリに SDD や AI 向けの PLAN を入れるのには今も否定的なので、人間向けも兼ねるこの形が気に入っている
- AI 専用みたいなドキュメントはあんまいらなくて人間が嬉しければ AI も嬉しい気はする、今は
SDD は 5 回くらいチャレンジしては挫折した、これくらいのライトさがよい
ADR は元々好きな考え方だったので盛り上がってきているのは嬉しい
on the web で Skill が使いづらい
Agentic Workflows よい

GitHub Agentic Workflows と通常の workflow を連携させたい

Sun, 08 Mar 2026 07:46:52 GMT

Agentic Workflows で何かしらの処理をした後に、その成果物に対してさらに GHA を動かしたいようなケースがある。わかりやすいところで言えば、Agentic Workflows でコードを変更したらテストが動いてほしいが、デフォルトでは Bot になるので、push をトリガーにする GHA (や外部サービス) が起動しない。

先にオチを書いておくと、2026/03/08 時点では用途にハマるものがなくて専用のユーザーの PAT を使い、通常のユーザーとして各種 Workflow などがトリガーされるようにした。

`safe-outputs.dispatch-workflow`

Safe Outputs | GitHub Agentic Workflows

Learn about safe output processing features that enable creating GitHub issues, comments, and pull requests without giving workflows write permissions.

github.github.com

safe-outputs に次のようにすると、指定した workflow がトリガーできるようになる:

safe-outputs:
  dispatch-workflow:
    workflows: [test, lint]
    max: 2

prompt から必要に合わせて呼び出す、safe-outputs は許可リストで、指定したら必ず呼び出させるようなものではないので注意。

Dispatch both `test` and `lint` workflows using the `dispatch-workflow` safe output,
passing the PR branch name as `ref` input.

ref としてブランチ名を渡しているが、 create-pull-request の場合に safe-outputs の処理内で branch にランダムな suffix が追加されるため、この名前はそのまま使えずこれをヒントにブランチを特定したりする必要があった。

reusable workflow

Safe Outputs | GitHub Agentic Workflows

Learn about safe output processing features that enable creating GitHub issues, comments, and pull requests without giving workflows write permissions.

github.github.com

workflow_on を使って reusable workflow として統合する形式で、今回やりたいことにはマッチしていそう。ドキュメントを読む限りでは needs.[job].outputs から issue や pr の情報が取れそうなのだが、現状これが取れなくてワークアラウンド的に途中に特定する job を挟んでいる。

name: Orchestrator

on:
  push:
    branches: [main]

jobs:
  run-agent:
    uses: ./.github/workflows/agent-task.lock.yml
    secrets: inherit

  find-pr:
    needs: run-agent
    runs-on: ubuntu-latest
    outputs:
      ref: ${{ steps.find.outputs.ref }}
    steps:
      - id: find
        run: |
          ref=$(gh pr list --repo "$GITHUB_REPOSITORY" --label documentation --state open --json headRefName --jq '.[0].headRefName // empty')
          echo "ref=$ref" >> $GITHUB_OUTPUT
        env:
          GH_TOKEN: ${{ github.token }}

  test:
    needs: find-pr
    if: needs.find-pr.outputs.ref != ''
    uses: ./.github/workflows/test.yml
    with:
      ref: ${{ needs.find-pr.outputs.ref }}

  lint:
    needs: find-pr
    if: needs.find-pr.outputs.ref != ''
    uses: ./.github/workflows/lint.yml
    with:
      ref: ${{ needs.find-pr.outputs.ref }}

Claude Code にコードを読んでもらった感じは以下の PR で対応が入っているが、出力される lock がそれを使うようになっていないんだとか、一旦できることがなさそうで修正待ちかという感じ。

feat: expose safe-output results as workflow_call outputs by Copilot · Pull Request #18914 · github/gh-aw

Workflows triggered via workflow_call had no way to surface results from safe-outputs (created issue numbers, PR URLs, commit SHAs, etc.) to callers. The compiled YAML never generated on.workflow_c...

github.com

この方法で branch に対してテストを走らせたりすることができるが、workflow が実行されるのはこの場合は main ブランチでなので、 commit や PR でテストを pass したことにはならない。

`safe-outputs.github-token`

そもそも Bot にしないというアプローチで、ユーザーが作ることになるので元々設定されている workflow が全部そのまま動く。

safe-outputs:
  github-token: ${{ secrets.USER_GH_TOKEN }}

output 毎に個別に設定することもできるが、自分が試したときはうまくいかなくて全体に設定してしまった。CodeRabbit が Bot だとデフォルトでは動かないみたいな話もあって、プライベートリポジトリに関してだけいえばこれで一旦良いかなとなった。

GitHub Agentic Workflows を使ってみる

Sun, 01 Mar 2026 20:26:37 GMT

GitHub Actions で AI を動作させる仕組みとして Agentic Workflows が追加されていて、これを試したメモ。

Automate repository tasks with GitHub Agentic Workflows

Build automations using coding agents in GitHub Actions to handle triage, documentation, code quality, and more.

github.blog

GitHub Agentic Workflowsを発表 - リポジトリの自動化を実現

itHub Agentic Workflowsがテクニカルプレビューとして登場。GitHub Actionsでコーディングエージェントを使用し、意図駆動型の自動化を構築しましょう。トリアージ、ドキュメント作成、コード品質向上など、さまざまなタスクを自動化できます。

github.blog

ざっくり言えば Markdown 形式でプロンプトを書き、Frontmatter に GHA の workflow ファイルに書くような設定を書くとそれをビルドして GHA で動作する [workflow].yml にしてくれる。

最近は変更点を ADR 形式で残す + 重要な点を ARCHITECURE.md や CLAUDE.md に反映するようなスタイルで開発をしていて、 main にマージした際に ARCHITRECURE.md への反映内容が間違っていないかを GHA で検証したかったので、そこに使ってみることにした。プロンプトはすでに Claude Code Action 向けに用意したものを使いまわしている、解説は割愛。

Agentic Workflows 用の Markdown は https://github.com/github/gh-aw/blob/main/create.md を読むことで作ることができるようになる。これを読むようにしながら、必要なものを作ってもらう。

https://github.com/github/gh-aw/blob/main/create.md を読んで、@.github/workflows/validate-docs.yml を Agentic Workflows に置き換えてください

これで以下のようなファイルができる:

---
description: Validate ARCHITECTURE.md and CLAUDE.md for factual accuracy against the current codebase
on:
  push:
    branches: [main]
permissions:
  contents: read
  issues: read
  pull-requests: read
tools:
  github:
    toolsets: [default]
  edit:
safe-outputs:
  create-pull-request:
    max: 1
    labels: [documentation]
  add-labels:
    allowed: [documentation]
---

# Validate Documentation

You are an AI agent that validates ARCHITECTURE.md and CLAUDE.md for factual accuracy against the current codebase.

### Scope

Only check for **incorrect** items. Do NOT:
- Add missing items or sections
- Remove items that are correct
- Suggest improvements or reorganization
- Change style or wording unless factually wrong

An item is "incorrect" when it describes something that contradicts the actual codebase — for example, a package name that doesn't exist, a wrong file path, a description that doesn't match what the code actually does, or a stated principle that the codebase explicitly violates.

### Steps

1. Read `.claude/skills/doc-writer/SKILL.md` to understand the documentation rules and structure
2. Examine the package structure under `packages/` (list directories, read package.json files and main entry points)
3. Examine `.github/workflows/` to understand where and how each package runs
4. Read `ARCHITECTURE.md` and validate every factual claim against the codebase
5. Read `CLAUDE.md` and validate every factual claim against the codebase
6. If no incorrect items are found, call the `noop` safe output with the message "No incorrect items found." and stop
7. If incorrect items are found:
   a. Fix only the incorrect items in ARCHITECTURE.md and/or CLAUDE.md using the edit tool
   b. Use the `create-pull-request` safe output with:
      - Branch name: `chore/fix-docs-YYYYMMDD` (where YYYYMMDD is today's date)
      - Commit message: `docs: fix incorrect items in ARCHITECTURE.md / CLAUDE.md`
      - Title: `docs: fix incorrect items in project documentation`
      - Body listing each incorrect item found and what was fixed

### Language Policy

Write commit messages, PR title, and PR body in English. Think in English.

### Output

- If changes were made, use the `create-pull-request` safe output to submit a PR with the fixes
- If no incorrect items were found, use the `noop` safe output to confirm that documentation is accurate

本文部分が実際に AI にやってほしいことのプロンプトで、Frontmatter には on: のような GHA でおなじみのものに追加して、この Workflow で Agent が生成できる成果物を safe-outputs として指定できる。ここで書き込めるものを指定しておくことで、安全に動かそうという仕組みのようだ。

Markdown を作ったら gh aw コマンドでビルドする。

$ gh extension install github/gh-aw
$ gh aw compile --strict [workflow-name]

無事ビルドができると workflow-name.lock.yml が作成される。これが実際に動作する workflow で、中身は見慣れた GHA の workflow ファイルになっている。

全体の流れを大雑把に言えば、 engine: copilot (デフォルト) の場合、 MCP やトークンの準備などを行い、 Markdown に書かれていたプロンプトとツール定義を合わて埋め込んだプロンプトを copilot-cli に渡して実行している。他には Frontmatter に設定した内容に沿って output の制御なんかをしていそうだが、詳しくは追っていない。

Copilot で動かすには PAT が必要で、engine を切り替えた場合はそれぞれ対応する API キーが必要。

Authentication | GitHub Agentic Workflows

Comprehensive reference for GitHub Actions secrets, GitHub tokens and GitHub Apps in gh-aw

github.github.com

$ gh aw secrets set COPILOT_GITHUB_TOKEN --value "token"

これで Workflow ファイルを push したら動いた。ちゃんと間違いを訂正する PR を作ってくれたので、しばらくはこれを使ってみようと思う。

Claude Code Action を GHA で動かすのとできることが大きく変わるわけではないが、あちらは一部の event をサポートしていないので、Agent SDK を使って構築するのもだるいような場合にはこちらが明確に有利か、というのがいまのところの感想。

Refs

Creating Agentic Workflows | GitHub Agentic Workflows

github.github.io

Custom Slash Command を Skills に変換する

Fri, 27 Feb 2026 08:03:42 GMT

少なくとも Claude Code では 2 つは統合されて、同じ扱いで呼び出すことができるようになっている。

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.

code.claude.com

Skill に寄せておくと他の Agent から使いたい場合に便利そうなので、必要なものを変換したい。 Custom Slash Command に互換のある、「ユーザーが呼び出すことができ、Agent が自動的に使用しない」という状態にするには、 Frontmatter で disable-model-invocation: true を指定する。

---
allowed-tools: Bash(git push), Bash(git diff), Bash(git log), Bash(gh pr create), Bash(which gh)
description: Create a pull request with structured format
user-invocable: true
disable-model-invocation: true
---

Create a pull request following the structured format. Analyze the current branch changes and generate appropriate content.

....

user-invocable: true はデフォルト値なので指定する必要がないが、自分は明示的に書いてしまっている。これらのフラグを逆にすると「Agent が自動的に使用することだけ許可」された Skill を作ることができる、そちらも用途はありそう。

Claude Code on the web / on desktop 向けの設定をした

Sat, 21 Feb 2026 00:00:00 GMT

ここ最近 Claude Code on the web を意識的に使うようにしていたら on desktop と worktree まわりにもアップデートが来たので、備忘録的に設定や使い方をまとめておく。これを触ったり書いているのが 2026/02 の 1-3 週目あたりで、ちょうど claude -w と Previews が入ったタイミングなので情報はすぐに古くなるかもしれない。まったく使ったことのない人向けの内容ではないので、どういうものかだったり基本的な使い方は公式を参照。

ウェブ上の Claude Code - Claude Code Docs

セキュアなクラウドインフラストラクチャで Claude Code タスクを非同期に実行します

code.claude.com

Claude Code Desktop を使用する - Claude Code Docs

Claude Code Desktop をさらに活用する：Git 分離による並列セッション、ビジュアル diff レビュー、アプリプレビュー、PR 監視、権限モード、コネクタ、エンタープライズ設定。

code.claude.com

前提として、専用になにかしらの設定をしなくともある程度は on the web が動作し、調査タスクや bugfix 程度であれば十分にワークしている。ここに少し設定を加えて便利になればよいなという温度感。また、 on the web と on desktop は同じ UI から利用できるが、中身は別物で有効な設定も違ったりするので注意。区別するために on the web と on desktop と書いている。

連携する GitHub アカウントを分ける

on the web の場合に、メインで利用しているものの中には Claude Code に触ってほしくないものが含まれている(可能性がある)のと、単純に UI に無数のリポジトリが表示されると扱いづらいので、専用のユーザーを作って必要なものだけアクセス権を与えて使うようにしている。自分の場合は前回の Issue 経由での開発フローで使っているユーザーが用途にマッチするのでそれをそのまま使っている。ユーザーの切り替えは単に Claude と連携している GitHub アカウントを切り替えれば OK。

DevContainer に ssh する

基本的には OrbStack + DevContainer で開発しているので、 on desktop の ssh 接続を使いたい。 DevContainer は ghcr.io/devcontainers/features/sshd を使うことで sshd を立てることができるのでこれを利用する。

Build software better, together

GitHub is where people build software. More than 150 million people use GitHub to discover, fork, and contribute to over 420 million projects.

github.com

必要なところだけ抜粋すると次のように devcontainer.json を設定している:

{
    "postCreateCommand": ".devcontainer/setup.sh",
    "features": {
        "ghcr.io/devcontainers/features/sshd:1": {}
    },
    "mounts": [
        "source=${localEnv:HOME}/.ssh/id_rsa.pub,target=/home/vscode/.ssh-host-authorized_keys,type=bind,readonly"
    ]
}

setup.sh:

# SSH authorized_keys setup (skip on Codespaces)
if [ -z "$CODESPACES" ] && [ -s "$HOME/.ssh-host-authorized_keys" ]; then
    mkdir -p ~/.ssh && chmod 700 ~/.ssh
    cp "$HOME/.ssh-host-authorized_keys" ~/.ssh/authorized_keys
    chmod 600 ~/.ssh/authorized_keys
fi

このように設定すると、 OrbStack を使っている場合はコンテナ名を調べて以下のコマンドで ssh できるようになる:

$ ssh -p 2222 vscode@condescending_dewdney.orb.local

あとはこれを on desktop で ssh 接続先として登録すれば使えるようになる。

ただし、この設定自体が Claude Code on desktop を使いたいという個人的なニーズに紐づいているので、プライベートリポジトリだけの運用になりそう。後述する Previews もこれを書いている時点では ssh には対応していないこともあり、使用頻度は低くなりそう。

SessionStart で依存の install

on the web でのセットアップ手順として SessionStart hooks を使った方法が公式に紹介されているが、これを on desktop と claude -w でも使えるようにしたい。

ウェブ上の Claude Code - Claude Code Docs

セキュアなクラウドインフラストラクチャで Claude Code タスクを非同期に実行します

code.claude.com

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/session-start.sh"
          }
        ]
      }
    ],
  }
}

session-start.sh で環境に合わせて必要なスクリプトを動かすようにしている:

#!/bin/bash

# Claude Code on the Web environment
if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
  bun install --no-save
fi

# Inside a worktree
if [[ "$PWD" == */.claude/worktrees/* ]]; then
  # Copy files listed in .worktreeinclude from the main working tree
  main_tree="$(git worktree list --porcelain | head -1 | sed 's/^worktree //')"
  include_file="$main_tree/.worktreeinclude"
  if [ -f "$include_file" ]; then
    while IFS= read -r entry || [ -n "$entry" ]; do
      [ -z "$entry" ] && continue
      src="$main_tree/$entry"
      [ -e "$src" ] && cp -a "$src" "$PWD/$entry"
    done < "$include_file"
  fi

  bun install --no-save
fi

.claude/worktrees 以下で実行されているなら on desktop か claude -w で動いているだろうという判定をしている。worktree 内で claude を起動し直すと少し無駄な感じになるが気になることはなさそう。

worktree の場合、後述する .worktreeinclude というファイルを読んで、 git 管理下にないファイルをコピーするようにしている。 claude 自体が持っている .worktreeinclude が claude -w の場合には動作しないのでその workaround。

on the web でたまに SessionStart が終わらないことがあり、おそらく bun install でネットワークに接続できていない(ログが見れないためよくわからない…)。クラウド環境の設定からネットワークアクセスをポチポチいじるとなおったりする。謎。

.worktreeinclude

Claude Code Desktop を使用する - Claude Code Docs

code.claude.com

昨今の流れ的にそれ自体がどうという話はあるが、 .env なんかを worktree にコピーしたいときに使える。元ファイルが必要なので on desktop 用で on the web の場合は代わりに環境変数を定義できる。 claude -w が出て、そちらはこのファイルには対応していないので、自分は前述のようにしている。

特に難しいことはなくて、.gitignore に入っているが worktree でも必要なファイルを同じフォーマットで列挙すればよい:

.env

PR のフォーマットを指定する

on the web では最終的に PR にして完結させることが多いのだが、 UI にある PR ボタンを押した場合に、これを書いている時点では CLAUDE.md を読んでいないように見える。一般的な PR のテンプレート + 英語で作られるのだが、これをカスタマイズしたくてもこれを書いている時点では方法がない。

幸いリポジトリにある Skills などは問題なく動作するので、PR を作るための Skills を user レベルから repository に移すことにした。そのままだと gh を使おうとするが on the web ではデフォルトでは gh が利用できず、あえて用意されていないようにも思うのでリンクを作らせるようにした。

大した内容ではないが、Skill の手順の最後をこんな感じにしている:

Check if `gh` CLI is available by running `which gh`
  - **If available**: Create the PR using `gh pr create` with the formatted body based on the template
  - **If not available**: Output a GitHub PR creation URL: `https://github.com/{owner}/{repo}/compare/main...{branch}?expand=1&title={url-encoded-title}&body={url-encoded-body}`

ただ、これはこれで PR を作成するのが今ブラウザでログインしているアカウントになってしまうため、分けている意味が少し薄れてしまうのがマイナス。そのうち解決しそうな話ではある。

2026/03/09 追記

デフォルトでも curl は動作するので、環境変数として PAT を設定して、フォールバックとして curl でのリクエストをするようにすると Skill 経由でうまくPR を作れるようになっているように思える。

#### Fallback: when `gh` fails

If `gh pr create` fails for any reason (not installed, auth error, API rate limit, etc.), fall back to creating the PR via `curl` using the GitHub REST API.

```bash
# Get repo info from remote URL
REMOTE_URL=$(git remote get-url origin)
# Extract owner/repo (handles both HTTPS and SSH formats)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's#(https://github\.com/|git@github\.com:)##; s/\.git$//')

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+v3+json" \
  "https://api.github.com/repos/$OWNER_REPO/pulls" \
  -d "$(cat <<'EOF'
{
  "title": "...",
  "body": "...",
  "head": "<branch>",
  "base": "<base-branch>"
}
EOF
)"

- Use `$GITHUB_TOKEN` or `$GH_TOKEN` environment variable for authentication (check both, prefer `GITHUB_TOKEN`)
- Escape JSON special characters in the title and body (double quotes, backslashes, newlines)
- Extract the PR URL from the response's `html_url` field

Previews for Claude Code

今のところ対応しているのが on desktop の Local だけなのでまだ使っていない。そのうち ssh や on the web でも対応してくれると嬉しいのだが…。

今の運用と雑感

個人的なリポジトリは on the web で十分に開発ができる + PR を出せば Preview URLs で動作確認が完結することもあってかなり使いやすい。 Issue ベースでの開発フローも整備してはいるので、それとの兼ね合いが少し曖昧になっているが、なんとなく以下の感じでやっている:

メインの開発はこれまで通り CLI
新しいことを試してみたり、調査タスクは on the web
バグレポートへの対応や、Issue として書いて残せるもの、一旦 Issue にしておいてあとで考えたいものは Issue ベース

CLI 以外は都度レスポンスすることがほとんどなくて、ポイポイと投げておいてあとで暇なときにまとめて確認している。自分は並列にいくつも Agent を動かすみたいなのが苦手であまりやっていなかったが、この運用だと少しできているのかなと思う。

on desktop の ssh と claude -w はこれまで自作の worktree 管理をしていたが、そっちは廃止して基本 claude に乗ることにした。

一方で on desktop の local がちょっと難しくて、これは単純に次のようなペインポイントがあって扱いに困ることがあるため:

on desktop で worktree を作るとき、 .worktreeinclude との兼ね合いなのかブランチを指定しても main worktree の状態から worktree が作られているように思う
diff 表示も少しおかしくて、常に main worktree が優先されている
Claude Code Desktop の Claude Code が NODE_EXTRA_CA_CERTS を見ていなくて、それ起因で環境によってはそもそも使えないことがある(Issue)

自分の場合は on desktop を使いたい環境で、現状では main worktree を綺麗に保つことが結構難しくて(例えば特定のパスに依存して動作するようなものがある環境)、 branch や diff がめちゃくちゃになってしまうし、そもそも Claude Code が動かなかったりする。 Codex App だとこのあたりがうまく動いていて、今はそっちを使っている。

ただ、Previews を使いこなせればフロントエンド開発にはかなり有効に思えるのでうまく使いたいとは思っている。

その他

on the web は常に push しているっぽいので、 GHA とか設定次第では結構使うかも
rewind ができないので困ることがある
AI Agent 全体的な話になってしまうが、 DevContainer のサポートが弱いのがぐぬぬという感じ、相性自体はいいはずなのだが…

claude-agent-sdk の output_format を zod で指定して任意の出力形式にする

Tue, 03 Feb 2026 17:58:31 GMT

@anthropic-ai/claude-agent-sdk を利用していて、その出力形式を自然言語形式ではなく特定の型の JSON にしたいケースがある。その場合 outputFormat で JSONSchema を指定することで任意の形式の出力を得ることができる。

query({
  prompt: '...',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema
    }
  }
})

これと zod 4x 以降でサポートされた toJSONSchema を組み合わせると、 zod で定義した型の JSON を出力として指定することが可能となる。

Get structured output from agents

Return validated JSON from agent workflows using JSON Schema, Zod, or Pydantic. Get type-safe, structured data after multi-turn tool use.

platform.claude.com

JSON Schema | Zod

How to convert Zod schemas to JSON Schema

zod.dev

しかし、 2026/02/04 時点では公式のドキュメント通りでは指定がうまく動作せず、自然言語で出力されてしまう。これは zod が吐き出す $schema フィールドが draft-2020-12 になっていることが原因のようで、draft-07 を指定することで動作するらしい。

Structured output ignored · Issue #105 · anthropics/claude-agent-sdk-typescript

Hi, if I try to use the structured output option, the LLM completely ignores it and outputs generic text. Could someone help me understand if there's a bug in the SDK? I'm following the example in ...

github.com

つまり現状では以下のようなコードで期待した structured_output を得ることができる:

query({
  prompt: '...',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: z.toJSONSchema(schema, { target: 'draft-07' })
    }
  }
})

code-simplifier が便利

Thu, 22 Jan 2026 12:44:13 GMT

Claude の公式のプラグイン集である claude-plugins-official で code-simplifier という subagent が提供されていてこれが結構便利。名前の通り、書いたコードをシンプルにしてくれる。

claude-plugins-official/plugins/code-simplifier/agents/code-simplifier.md at main · anthropics/claude-plugins-official

Official, Anthropic-managed directory of high quality Claude Code Plugins. - anthropics/claude-plugins-official

github.com

JavaScript is not available.

x.com

自分はこれを Custom Slash Command で呼び出して、変更したらテストを実行するようにして使っている。

---
description: Simplify and refactor code while ensuring tests pass
allowed-tools: Task(code-simplifier:code-simplifier)
---

Simplify and refactor code using the code-simplifier subagent, then verify behavior is unchanged by running tests.

## Instructions

1. Use the `code-simplifier:code-simplifier` subagent to perform the refactoring
   - Focus on clarity, consistency, and maintainability
   - Preserve all existing functionality
2. After refactoring, run the project's test suite to verify behavior is unchanged
3. If tests fail, investigate and fix any regressions introduced by the refactoring
4. Report the changes made and test results

## Additional Context

$ARGUMENTS

> /code-simplifier
> /code-simplifier @src/index.ts をリファクタリングして

CLAUDE.md に毎回実行してと書いておくのもよさそうだが、そこそこ実行コストが高いように感じているので、今のところは明示的に呼び出すようにしている。

Claude Code で respectGitignore を設定して個人用ファイルを @ で補完できるようにする

Wed, 14 Jan 2026 21:03:24 GMT

Claude Code では @src/index.ts のようなファイル参照はこれまで gitignore を尊重する動作になっていたが、これが 2.1.0 で OFF にできるようになった。

claude-code/CHANGELOG.md at main · anthropics/claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflo...

github.com

{
  "respectGitignore": false
}

これで何が嬉しいかというと、例えば個人用のメモや Git 管理していない PLAN.md のようなファイルを Claude Code に渡したい場合に、それが gitignore されていると補完が効かないという問題があった。これは Issue にもなっている。

[FEATURE REQUEST] Allow Claude Code to access gitignored files · Issue #2305 · anthropics/claude-code

Current Behavior Claude Code currently respects .gitignore files and excludes gitignored files from: @-mention autocomplete suggestions General file awareness and reading (unless explicitly request...

github.com

[FEATURE REQUEST] Allow Claude Code to access gitignored files · Issue #5105 · anthropics/claude-code

github.com

自分の場合はオレオレ実装計画を Git 管理しない形で作って使っているので、false にできると嬉しい。ただし、node_modules なんかも対象になってしまうことに注意。

仕様駆動開発風のオレオレ実装計画を作って AI と併走する - yaakai.to

🐧 仕様駆動開発風のオレオレ実装計画を作って AI と併走する | yaakai.to

yaakai.to

Claude Code で LSP サポートを使う

Mon, 12 Jan 2026 19:36:57 GMT

以前のバージョンから LSP のサポートがあることは releasenote に記載されていたが、不具合で実質的に動作していなかったものが 2.1.0 で解消された。

claude-code/CHANGELOG.md at main · anthropics/claude-code

github.com

これまで古いバージョンで自作の plugin を作る必要があったが、公式の marketplace にあるものを利用することが出来るようになっている。例えば TypeScript の場合は以下:

$ claude plugin install typescript-lsp@claude-plugins-official
$ npm install -g typescript-language-server typescript
$ ENABLE_LSP_TOOL=1 claude

claude-plugins-official/plugins/typescript-lsp at main · anthropics/claude-plugins-official

Official, Anthropic-managed directory of high quality Claude Code Plugins. - anthropics/claude-plugins-official

github.com

ただ、2.1.5 現在でも動作させるためには ENABLE_LSP_TOOL フラグが必要。releasenote やドキュメントそのような記載はないためなんとも言えないが、現状はまだ Experimental な機能ということだろうか？

Claude Code の言語を settings.json で設定する

Thu, 08 Jan 2026 07:13:26 GMT

これまでは CLAUDE.md で言語を指定することが多かったが、2.1.0 で settings.json で language がサポートされた。

claude-code/CHANGELOG.md at main · anthropics/claude-code

github.com

日本語の場合は以下のように設定すると、CLAUDE.md で指定することなく日本語でレスポンスが返されるようになる。

{
  "language": "japanese",
}

Issue 起点の開発フローを claude-code-action と CodeRabbit で作った

Wed, 31 Dec 2025 00:00:00 GMT

適当な Issue を AI に実装したり一度試してもらいたいときに、これまでは @claude したり git-worktree を使った裏での実行をしていたが、これを GitHub 上でレビューまで完結するようにしたかったのでフローを作った。 private リポジトリでしばらく使っていたが、このブログのリポジトリにも移植してきたのでこのタイミングでまとめておく。

やっていること

Issue に特定のラベルをつけると GHA が起動して、 Claude Code による実装と CodeRabbit でのレビュー、その修正が自動で行われる。可能なものは Cloudflare Workers の Preview URLs を発行していて、それが PR に貼られるのでそこで動作確認をしている。

流れを書くとこんな感じ:

Issue テンプレートから ai-automate:claude ラベル付きで Issue を作成
GHA が起動して、Issue 内容をもとに Claude Code が実装を行い、PR を作成
- Preview URLs を発行
CodeRabbit が PR をレビューして、 Approved か Request Changes を通知
レビュー通知に合わせて GHA が起動
- Approved の場合は Claude Code を使ってレビューをして内容をコメント
- Request Changes の場合は Claude Code で修正を行い、 Approved されるまで繰り返す

このフローを基本としつつ、今は CodeRabbit が Plan を作ってくれるようになったので、その Plan に基づいて実装を行うフローも追加している。ただ、 Plan が作られるトリガーがよく分かっていなくて動作が不安定。 CodeRabbit からのコメントをトリガーにしているが、それが来ないことがある。

Why CodeRabbit?

AIコードレビュー | CodeRabbit | 無料トライアル可能

コンテキストを理解したフィードバック、行単位のコード提案、リアルタイムチャットを備えたAIファーストのプルリクエストレビュアー

www.coderabbit.ai

レビューの精度みたいな話を一旦抜きにして、 Approved と Request Changes を送ってくれるからというのがある。というよりは、元々 CodeRabbit を試していて、これをしてくれるのでこのフローを作ってみようと思った。 AI によるコードレビューだと Claude Code にやらせたり、 GitHub Copilot や Greptile を使うという方法が他にもあるが、 PR レビューの承認や変更要求を自動で行ってくれるものはないはずなので CodeRabbit を採用している。

レビュー内容に関しても今のところそこまで不満はないが、少し遅めなのと、細かすぎる(Nitsや揚げ足取り的な内容)のではと思うことは多少ある。が、特に今回のように修正を AI が行ってくれる場合は細かい分には嬉しいので、プラスかなと捉えている。遅いのも基本的には放置してあとで見るのであまり気にならない。

ただ、最終的には Claude Code のレビューも兼用するようにしている。 push 毎に Claude Code がレビューすると PR が荒れがちになるのが気になっていたが、 CodeRabbit の Approved 後にすることでちょうどよくなったと思う。

また、まだ効果が実感できていないので期待になってしまうが、CodeRabbit や Greptile のようなツールを使うことで、レビューの内容を学習(した記録を外付け)できることに魅力を感じている。

AI Code Review | Greptile | Merge 4X Faster, Catch 3X More Bugs

AI Code Reviews that understand your entire codebase. Automate PR reviews, catch bugs faster, improve code quality with AI-driven analysis. Try Greptile free!

www.greptile.com

あと Poem がかわいい。

Examples

作った Issue と PR の例:

パンくずリストの実装 · Issue #122 · yaakaito/yaakaito

各記事ページの左上部分にパンくずリストを追加する。 / 区切りのテキストベースで行い、現在のページは含めない yaakai.to / blog / これに伴って、日付の位置をタイトルの下に変更する。

github.com

パンくずリストの実装 by nullkite · Pull Request #125 · yaakaito/yaakaito

各記事ページの左上部分にパンくずリストを追加し、日付の位置をタイトルの下に変更しました。 Key Changes web/src/components/Breadcrumb.astro - パンくずリストコンポーネントを新規追加 web/src/layouts/blog-post.astro - レイアウトを更新してパンくずリストを追加し、日付の位置を変更 Technical Detai...

github.com

ここでは Approved されているのでそれで終わっているが、 Request Changes された場合はさらに修正が自動で行われる。例えばこれは何度かやりとりを繰り返してる:

注釈は Pop Over で Top Layer に出すようにする by nullkite · Pull Request #127 · yaakaito/yaakaito

注釈リンクをクリックするとスクロールせずにその場でポップオーバーで注釈内容を表示できるようにしました。 Key Changes web/src/layouts/blog-post.astro: CSS Anchor Positioning を使用した注釈ポップオーバーの実装 Technical Details CSS Anchor Positioning API を使用してアンカー要素...

github.com

GitHub Actions の workflow

Preview URLs 用のものを含めると 3 つの workflow で構成している。Preview URLs は適当に wrangler versions upload すればよいだけなのでここでは割愛、GitHub にこのリポジトリのものが置いてある。

WARNING

この workflow は移植するにあたって、調整を行っている場所がいくつかあって、十分に確認はできていないのでそれが原因で動作しない可能性がある。

NOTE

PR を作るのが Bot だと CodeRabbit が反応せず、これを変更する設定もなかった(2025/12/31 時点)ので、PR を作成するために PAT なりを用意する必要がある。メインで使っているアカウントの PAT でもよいのだが、変更できる範囲を限定したいのと、通知が多くなりすぎてしまうので、自分は専用のアカウントを作ってそれの PAT を使っている。ただし、 private リポジトリで使う場合はそのユーザーの分も CodeRabbit の seat が必要になるので注意。

まず、 Issue に ai-automate:claude ラベルがつけられたときに起動する workflow:

name: Automate with Claude

on:
  issues:
    types: [labeled]

jobs:
  automate-issue:
    if: github.event.label.name == 'ai-automate:claude'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - name: Create branch for issue
        env:
          GH_TOKEN: ${{ secrets.AI_USER_GH_TOKEN }}
        run: |
          BRANCH_NAME="claude/automate-${{ github.event.issue.number }}-$(date +%Y%m%d-%H%M)"
          git checkout -b "$BRANCH_NAME"
          git push -u origin "$BRANCH_NAME"
          echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.AI_USER_GH_TOKEN }}
          prompt: |
            Read the issue and implement the requested changes.

            Note: A branch named "${{ env.BRANCH_NAME }}" has already been created and checked out for this issue.

            ## Language Policy

            Use the same language as the issue for commits, PR title, and PR body.

            ## Workflow

            1. Use mcp__github__get_issue to read and understand the issue
            2. Check CLAUDE.md for repository-specific guidelines
            3. Implement the changes
            4. Commit and push changes to the current branch
               - Include Co-authored-by: ${{ github.event.issue.user.login }} <${{ github.event.issue.user.id }}+${{ github.event.issue.user.login }}@users.noreply.github.com>
            5. Read .claude/skills/pr-template/SKILL.md for PR template, then create PR with mcp__github__create_pull_request
            6. Add "ai-automate:claude" label to the created PR
            7. Comment the PR URL to the issue using: gh issue comment ${{ github.event.issue.number }} --body "Created PR: [PR_URL]"
          claude_args: |
            --allowedTools "Bash,Write,Edit,Read,Glob,Grep,Task,mcp__github__get_issue,mcp__github_comment__update_claude_comment,mcp__github__create_branch,mcp__github__create_pull_request,mcp__github__update_issue,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh issue comment:*)"

Claude Code に実装させ、実装が終わったら PR を作成させている。

branch を先に作っているのは、たまに main へそのまま commit して push してしまうことがあったため。 branch protection ルールで守るなどの方法もあるが、ブランチ名が衝突しても面倒そうなので手動で作ることにしている。

PR に書く内容は Skill 化しているのだが、claude-code-action 内で Skill がうまく動かないので SKILL.md を直接読むように指示している。

次に、PR が CodeRabbit によってレビューされたときに起動する workflow:

name: Claude Fix Unresolved Reviews

on:
  pull_request_review:
    types: [submitted]

jobs:
  # CodeRabbitのrequested changes時に自動修正を実行
  fix-requested-changes:
    if: |
      github.event_name == 'pull_request_review' &&
      github.event.review.state == 'changes_requested' &&
      github.event.review.user.login == 'coderabbitai[bot]' &&
      contains(join(github.event.pull_request.labels.*.name, ','), 'ai-automate:')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - name: Checkout PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr checkout ${{ github.event.pull_request.number }}
      - name: Fetch unresolved reviews
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          OWNER=$(echo "${{ github.repository }}" | cut -d/ -f1)
          REPO=$(echo "${{ github.repository }}" | cut -d/ -f2)
          PR_NUMBER=${{ github.event.pull_request.number }}

          RESULT=$(gh api graphql -f query='
          query($owner: String!, $repo: String!, $number: Int!) {
              repository(owner: $owner, name: $repo) {
                  pullRequest(number: $number) {
                      reviewThreads(first: 100) {
                          nodes {
                              isResolved
                              isOutdated
                              path
                              line
                              comments(first: 10) {
                                  nodes {
                                      author { login }
                                      body
                                  }
                              }
                          }
                      }
                  }
              }
          }' -f owner="$OWNER" -f repo="$REPO" -F number="$PR_NUMBER")

          echo "$RESULT" | jq -r '
              .data.repository.pullRequest.reviewThreads.nodes
              | map(select(.isResolved == false and .isOutdated == false))
              | if length == 0 then
                  "<no-unresolved-comments />"
                else
                  .[] |
                  "<review-comment>",
                  "  <file>\(.path // "unknown")</file>",
                  "  <line>\(.line // "unknown")</line>",
                  "  <author>\(.comments.nodes[0].author.login // "unknown")</author>",
                  "  <body>\(.comments.nodes[0].body // "")</body>",
                  "</review-comment>",
                  ""
                end
          ' > .git/unresolved_reviews.xml
      - uses: anthropics/claude-code-action@v1
        with: &claude-code-fix-reviews
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.AI_USER_GH_TOKEN }}
          allowed_bots: coderabbitai[bot]
          track_progress: true
          prompt: |
            Fix unresolved review comments on this GitHub PR.

            ## Steps

            1. Read the file `.git/unresolved_reviews.xml` which contains unresolved review comments.
            2. Review each comment and apply the necessary fixes.
               - If the file contains `<no-unresolved-comments />`, exit.
            3. Commit after each fix.
            4. Repeat until all fixes are complete.
            5. Push the branch to remote when all fixes are done.
          claude_args: |
            --allowedTools "Bash,Write,Edit,MultiEdit,Read,LS,Glob,Grep,mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

  # CodeRabbitのapproved時にClaude Codeレビューを実行
  claude-review-after-approval:
    if: |
      github.event_name == 'pull_request_review' &&
      github.event.review.state == 'approved' &&
      github.event.review.user.login == 'coderabbitai[bot]'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 1
      - name: Checkout PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr checkout ${{ github.event.pull_request.number }}
      - name: Run Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          allowed_bots: coderabbitai[bot]
          track_progress: true
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}

            Perform a comprehensive code review in the same language as the Pull Request description with the following focus areas:

            1. **Code Quality**
               - Clean code principles and best practices
               - Proper error handling and edge cases
               - Code readability and maintainability

            2. **Security**
               - Check for potential security vulnerabilities
               - Validate input sanitization
               - Review authentication/authorization logic

            3. **Performance**
               - Identify potential performance bottlenecks
               - Review database queries for efficiency
               - Check for memory leaks or resource issues

            4. **Testing**
               - Verify adequate test coverage
               - Review test quality and edge cases
               - Check for missing test scenarios

            5. **Documentation**
               - Ensure code is properly documented
               - Verify README updates for new features
               - Check API documentation accuracy

            Provide detailed feedback using inline comments for specific issues.
            Use top-level comments for general observations or praise.

          claude_args: |
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

前提として、 PR が作られると CodeRabbit のレビューが自動に開始される必要がある。 Approved された場合は Claude Code によるレビューを行い、 Request Changes された場合は Claude Code による修正を Approved されるまで繰り返す。レビュー用の prompt は claude-code-action に組み込まれているものと同じはず。

ここでもレビューコメントの取得を Skill 化したものを使いたかったが、一旦妥協して workflow 内に直接 script を書く形にしている。未解決のレビューを取得するよう prompt で指示するだけでも十分に思えるが、 GitHub 上で resolved されたものの判別がうまくできないことが何度かあって、確実に動かすためにこうしている。

ちなみに claude-code-action の場合も次のような設定をすることで Plugin を使うことができる。

plugin_marketplaces: https://github.com/yaakaito/env.git
plugins: base@yaakaito-env

雑感

軽い実装であれば Preview URLs も合わせて GitHub 上で動作確認までできて便利
- メインの作業中に思いついたことを雑に Issue にして投げておける
- 必要であれば修正を @claude で投げればよい
Skill が動いてほしい、動きそうなのだが…
- ただの md なので直接読めばよいという恩恵を受けている感じがある
- --allowedTools が足りないとかではなく ❌ Error: Execute skill: pr-template のように失敗してしまう
track_progress を使うと beta 版のように進捗を Issue Comment としてアップデートしてくれて便利な上 branch の問題も解決する
- ただ、Mention が毎回飛んでくるのでちょっとだるい感じになる
- 放置しておいてあとでまとめて確認したい
修正を push してもたまに CodeRabbit が反応しないことがある
- Plan がこないのも同じ理由なのだろうか？

CLAUDE.md を作る skill を作って整理する

Sat, 20 Dec 2025 19:48:04 GMT

これまで /init したものに適当に書き足したものを CLAUDE.md や AGENTS.md として使ってきたが、いくつか記事を読んだり参考になる CLAUDE.md を見たりで整理したい気持ちになったので整理した。いくつか管理しているリポジトリに適用していきたかったので、 Claude Code の Plugin として skill にしている。

File not found · yaakaito/env

Contribute to yaakaito/env development by creating an account on GitHub.

github.com

整理するにあたって、以下のことを意識して作るようにした:

最小限であること
現状を尊重すること
リポジトリ単位では、人間がやってほしいワークフローを押し付けないこと
常に使うものでないなら、別ドキュメント / skills / slash command に切り出すこと

最終的に次のような構成になった:

このリポジトリの目的、アプリケーションの簡単な説明

## Architecture Overview

- どのように作られ、動いているかの概要を数行で書く  
- 例えば Cloudflare Workers と KV を使って構築している

## Directory Structure

- よく触ることになるファイルのポインタ

## Core Principles

- 現状を尊重してほしいとか、一般的によいとされる開発をしてねとか、消すこともある
- リポジトリで特に重要なコーディング原則などがあれば書き足す

## Commands

- 普段使うコマンド

## Testing

- モックは最小限にしてほしいとか
- リポジトリで必要なことや方針があれば書き足す

## Language Policy

- AI 向けのドキュメントは英語で書いてほしい
- 他はユーザーに任せる

## Additional Resources

- 特に重要な ADR や ARCHITECURE.md へのリンク

これに加えて設計の記録である ADR 、全体の設計を詳しく書いた ARCHITECURE.md 、リポジトリごとの固有の BEST_PRACTICES.md をだいたいの場合で作るようにしている。要所で守ってほしいルールはだいたい skill 化していて、例えば ADR のフォーマットを skill にして書くときに読んでもらうようにしている。他には PR のフォーマットとかフロントエンドの実装ガイドラインなんかが便利。

これに加えて、言語の設定や推奨したいコーディング、ワークフローを書いた ~/.claude/CLAUDE.md を使っている。大した内容ではないが。

File not found · yaakaito/env

Contribute to yaakaito/env development by creating an account on GitHub.

github.com

所感としては、これまで /init なりで作っていた比較的大きいものから移行しても大して困っていないので、これくらいで十分なんだなという肌感はある。 Core Principles にちょっと抽象的なことを書いているが効いているかよくわからない。Language Policy を書いたのが結構良くて、AI 向けのものをこれまで英語で書かれたり日本語で書かれたりしていたのがなくなった(元々が日本語ならそうなるが…)。

Refs

読んだ記事:

Writing a good CLAUDE.md

`CLAUDE.md` is a high-leverage configuration point for Claude Code. Learning how to write a good `CLAUDE.md` (or `AGENTS.md`) is a key skill for agent-enabled software engineering.

www.humanlayer.dev

Skill authoring best practices

Learn how to write effective Skills that Claude can discover and use successfully.

platform.claude.com

参考にさせていただいた CLAUDE.md とか:

BPlusTree3/rust/docs/CLAUDE.md at main · KentBeck/BPlusTree3

A plug-compatible replacement of Rust's BTree collection - KentBeck/BPlusTree3

github.com

kopi/AGENTS.md at main · kopi-vm/kopi

Contribute to kopi-vm/kopi development by creating an account on GitHub.

github.com

serena/CLAUDE.md at main · oraios/serena

A powerful coding agent toolkit providing semantic retrieval and editing capabilities (MCP server & other integrations) - oraios/serena

github.com

codex/AGENTS.md at main · openai/codex

Lightweight coding agent that runs in your terminal - openai/codex

github.com

Codex CLI でも Skills を使う

Mon, 08 Dec 2025 18:06:25 GMT

Experimental だが、v0.65.0 で Codex CLI でも Claude (Code) の Skills と同等のものがサポートされた。

Release 0.65.0 · openai/codex

Highlights Codex Max as default (#7566): Codex Max is now the default model, and a TUI panic related to async-in-sync code was fixed. Better resume UX (#7302, #7303): Added a /resume slash command...

github.com

codex/docs/skills.md at main · openai/codex

Lightweight coding agent that runs in your terminal - openai/codex

github.com

laiso さんの書かれている内容とほとんど同じになってしまうが、備忘録的に自分の使い方を残す。

Codex CLI が Skills をサポート

Codex CLI の最新版v0.65.0 において、experimental ではありますが Skills のサポートが導入されました[1]。 codex/docs/skills.md at main · openai/codexLightweight coding agent that runs in your terminal - openai/codexGitHubopenai [1]: https://github.com/openai/codex/pull/7412 Claude Skills と同じ形式のディレクトリを配置するだけで読み込まれるため、導入の手間はほとんどありません。設定としては、config.toml に次の一行を追加します。 [features] skills = true スキルパッケージは ~/.codex/

blog.lai.so

使用するには ~/.codex/config.toml でフラグを設定し、 ~/.codex/skills 以下にスキルを配置する必要がある。

[features]
skills = true

自分は基本的に開発を DevContainer で行っていて、コンテナが Rebuild される際に設定される Dotfiles Repository に設定をまとめたかったので、Claude Code 向けに Plugin にしているものからセットアップの際にコピーすることにした:

cp -r ./.codex ~/.codex
cp -r ./cc-plugins/dev-plan/skills/adr-writer ~/.codex/skills/adr-writer
cp -r ./cc-plugins/skills/skills/frontend-design ~/.codex/skills/frontend-design

_{https://github.com/yaakaito/env/blob/main/setup.sh#L9-L11}

frontend-design は anthropics/skills のもので、扱いやすいようリポジトリに取り込んでいる。Claude Code Plugin のように付け外しが気楽にできる仕組みになっていないのが惜しいが、どちらもで使うという意味であれば十分そうだ。

Codex CLI では $ で Skill が参照でき、これは Claude Code にはない利点。

$frontend-design を使って xxx を ....

Refs

feat: experimental support for skills.md by tibo-openai · Pull Request #7412 · openai/codex

This change prototypes support for Skills with the CLI. This is an experimental feature for internal testing.

github.com

プラグインを作成する - Claude Code Docs

スキル、エージェント、フック、MCP サーバーで Claude Code を拡張するカスタムプラグインを作成します。

code.claude.com

bun test や vitest の onTestFinished Hook

Tue, 18 Nov 2025 18:39:40 GMT

Bun v1.3.2 で追加され、 Vitest でもサポートされている機能として onFinishedTest という Hook がある。

Bun v1.3.2 | Bun Blog

Fixes 287 issues (addressing 324 👍). Hoisted installs restored as default for backward compatibility. CPU profiling with --cpu-prof, faster installs for packages with post-install scripts, bun:test onTestFinished hook, ServerWebSocket subscriptions getter, Alpine 3.22 in Docker images, improved Git dependency resolution, bun list alias, and numerous bug fixes across install, HTTP/HTTPS, N-API, bun test, bun build, and runtime.

bun.com

Vitest

Next generation testing framework powered by Vite

vitest.dev

これは各テストの終了時に実行されるフックで、afterEach よりあとで実行され、テストの成否に関わらず実行されるため、テストで必要だったリソースの解放などに使うことが出来る。

import { afterEach, describe, expect, onTestFinished, test } from 'bun:test';

describe('onTestFinished Hook', () => {
    afterEach(() => {
        console.log('afterEach called');
    });
    test('example', () => {
        onTestFinished(() => {
            console.log('example 1 onTestFinished called');
        });
        expect(1 + 1).toBe(3);
    });
    test('with Error', () => {
        onTestFinished(() => {
            console.log('example 2 onTestFinished called');
        });
        throw new Error();
    });
});

これを実行すると次のようになる:

test/hook.test.ts:
 6 |     });
 7 |     test('example', () => {
 8 |         onTestFinished(() => {
 9 |             console.log('example 1 onTestFinished called');
10 |         });
11 |         expect(1 + 1).toBe(3);
                           ^
error: expect(received).toBe(expected)

Expected: 3
Received: 2

      at <anonymous> (/workspaces/aiblio/test/hook.test.ts:11:23)
afterEach called
example 1 onTestFinished called
✗ onTestFinished Hook > example

12 |     });
13 |     test('with Error', () => {
14 |         onTestFinished(() => {
15 |             console.log('example 2 onTestFinished called');
16 |         });
17 |         throw new Error();
                             ^
Error: 
      at <anonymous> (/workspaces/aiblio/test/hook.test.ts:17:25)
afterEach called
example 2 onTestFinished called
✗ onTestFinished Hook > with Error

 0 pass
 2 fail
 1 expect() calls
Ran 2 tests across 1 file. [62.00ms]

Chrome DevTools MCP を DevContainer(OrbStack) から使う

Sat, 08 Nov 2025 19:02:42 GMT

普段 DevContainer で開発している中で DevTools MCP を使いたいが、 Chrome が入っていないコンテナから利用するには設定が必要なのでそのメモ。ホスト側の Chrome を使うようにする。

AI エージェント用の Chrome DevTools（MCP）  |  Blog  |  Chrome for Developers

新しい Chrome DevTools MCP サーバーの一般公開プレビュー版。Chrome DevTools の機能を AI コーディングアシスタントに提供します。

developer.chrome.com

基本的な設定方法は DevTools MCP の README に書かれていて、DevContainer 専用ではないが --browser-url というオプションに remote debugging port を有効にした Chrome を指定することが出来る。

GitHub - ChromeDevTools/chrome-devtools-mcp: Chrome DevTools for coding agents

Chrome DevTools for coding agents. Contribute to ChromeDevTools/chrome-devtools-mcp development by creating an account on GitHub.

github.com

remote debugging port は 136 以降で --user-data-dir オプションを兼用しないと有効にできなくなっている。今回は Chrome を普段遣いのものとは別で開きたかったので、すべてまとめると次のコマンドで MCP から利用する Chrome を起動できる。Raycast の Script Commnad として適当に登録した。

$ open -n -a "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/devtools-mcp

Chrome が起動したらコンテナ側から接続するホスト側の IP を調べる。host.docker.internal でアクセスできそうだが、Chrome 側の制約で拒否されてしまった。

$ getent hosts host.docker.internal
> 0.250.250.254   host.docker.internal

_{ちなみにコンテナから curl を投げてみるとこんな感じになる:}

$ curl http://host.docker.internal:9222/json/version                     
Host header is specified and is not an IP address or localhost.%                                                                                             
$ curl -H "Host: localhost" http://host.docker.internal:9222/json/version
{
   "Browser": "Chrome/142.0.7444.60",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
   "V8-Version": "14.2.231.14",
   "WebKit-Version": "537.36 (@e7848b4d5b3843432464a9b8237fe58e87f6c357)",
   "webSocketDebuggerUrl": "ws://localhost/devtools/browser/9e8b5696-17d3-4b14-82cf-1f5975b571b7"
}
$ curl http://0.250.250.254:9222/json/version                     
{
   "Browser": "Chrome/142.0.7444.60",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
   "V8-Version": "14.2.231.14",
   "WebKit-Version": "537.36 (@e7848b4d5b3843432464a9b8237fe58e87f6c357)",
   "webSocketDebuggerUrl": "ws://0.250.250.254:9222/devtools/browser/9e8b5696-17d3-4b14-82cf-1f5975b571b7"
}

これを引数に起動するように .mcp.json などを調整する。自分は Claude Code を使っているので、Plugin としてこの設定を install 出来るようにした。

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://0.250.250.254:9222"
      ]
    }
  }
}

設定がうまく行っていれば次のような適当なコマンドを実行すると、ホスト側の Chrome が動いて確認できるはず。

chrome-devtools を使って yaakai.to の Core Web Vitals を測定して

Refs

ポート転送でローカルサーバーと Chrome インスタンスにアクセスする  |  Chrome DevTools  |  Chrome for Developers

開発マシンのウェブサーバーでサイトをホストし、Android デバイスからコンテンツにアクセスする。

developer.chrome.com

セキュリティを強化するためのリモートデバッグスイッチの変更  |  Blog  |  Chrome for Developers

--remote-debugging-port と --remote-debugging-pipe の動作の変更を発表します。

developer.chrome.com

Chrome DevTools Protocol

Chrome DevTools Protocol - version tot

chromedevtools.github.io

実装計画を Vibe Kanban で並列に開発する

Tue, 04 Nov 2025 00:00:00 GMT

Coding Agent でタスクリストや実装計画を立てて開発を行っていると、作業を並列に進めることができるシーンが度々ある。いままではこれを git-worktree を利用したり、可能であれば GitHub の Issue として登録することで進めていたが、Vibe Kanban を使うことで快適に行えそうだったので試した。Vibe Kanban の使い方を細かく解説するような内容ではない。

Vibe Kanban

Vibe Kanban - Orchestrate AI Coding Agents

Get the most out of coding agents like Claude Code, Gemini CLI and Amp. Orchestrate multiple AI coding agents, track tasks, and manage your development workflow efficiently.

www.vibekanban.com

Vibe Kanban - Vibe Kanban

Plan and review the work of AI agents faster, ship more

www.vibekanban.com

git-worktree をうまく扱えるツールだと認識している。git-worktree を利用して、複数の Coding Agent のインスタンスを同時に立ち上げ、それぞれを管理することができる。自分は名前から勘違いしていたが、 GitHub の Issue を並列で実装できる、というようなツールではない。そのような使い方もできるとは思うが。

複数の Project(Repository?) を扱えるようなので明記しておくと、自分は Dev Container で開発しているので /workspaces/repo で npx で Vibe Kanban を起動している:

cd /workspaces/repo
npx vibe-kanban

起動すると URL が発行されるので Web ブラウザで開く。 GitHub と連携すると PR を作成したりできるが、今回の用途では連携しなくとも問題ないはず。

実装計画を作って MCP Server を利用してタスクを登録する

Vibe Kanban 自体がなにかタスクを分割するような機能を持っているわけではないので、好みのツールやフォーマットで実装計画を作って、タスクリストを作る。このタイミングで、並列に開発が行えるタスクは依存関係を含めて分割しておく。今回は設計とタスクリストをまとめて PLAN.md として保存している。

タスクが分割できたら Vibe Kanban に取り込むのだが、 MCP Server が用意されているのでこれを利用するとタスクの登録を Coding Agent でできるようになる。今回は Claude Code を使用している。

Vibe Kanban MCP Server - Vibe Kanban

Configure the Vibe Kanban MCP server

www.vibekanban.com

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "npx",
      "args": ["-y", "vibe-kanban@latest", "--mcp"]
    }
  }
}

設定ができたら次のようなプロンプトを実行する:

@PLAN.md を確認して、作業計画を Task 単位で vibe_kanban へ Task として登録してください。
タスクには以下の内容を記載します:

- 設計は @PLAN.md を参照すること
- このタスクでの具体的な作業内容
- 依存する他のタスクや、並列作業が可能かどうか
- 並列実行できる場合は、タイトルに + をつけてください

タスクは降順に登録してください。

「降順に登録」が割と重要で、これがないと Vibe Kanban 上のタスクリストが逆になってしまうはず。現状タスクのソート機能がなく、常に登録された順番に表示されるためこれを入れたほうがよいと思う。

登録されたタスクは Attempt を追加して実行する。デフォルトではリポジトリで switch している branch からタスクを実装するようになっている。今回は Vibe Kanban でコードの確認までした worktree を実装計画用の作業 branch に随時マージしていき、 VSCode 側で作業 branch を使って人間が動作確認するようなスタイルにした。

また、今回自分は Vibe Kanban で計画を作ったが、タスク登録を考えると計画には Claude Code なりをそのまま利用したほうがよいと思う。

並列での実装とレビュー

並列で実装が行えるタスクになったら、それぞれに Attempt を追加して実行する。実行中のタスクはすべて In Progress に移動したあと、終わったものから In Review に移動していくので、レビューを行う。

レビューは Vibe Kanban 内の UI で行うことができる。開発サーバーを連携することでライブプレビューも利用できるようだが、今回は試していない。

このレビュー UI はもともと VSCode 上で行っていたスタイルと似ていて使いやすい。行単位にレビューしつつも、レビューごとに修正を行うのではなくまとめて依頼することができるようになっていて便利。

レビューを送信するとまた In Progress に移動するので、これを繰り返して納得できるコードを生成する。生成したら Merge すると内容が作業 branch に反映され、動作確認してタスク完了となる。複数のタスクを並列に進めている場合はしょっちゅう Conflict するが、 Web UI から rebase を要求できるようになっているのでこれを使って解決する。

あとはすべてのタスクが完了するまでこれを繰り返す。途中、ある程度コードを変更したタイミングで PR を作り、CodeRabbit にレビューしてもらったものを修正しながら進めた。

雑感

AI にコードを書かせている途中で思いついたタスクを追加したいことはよくあるが、Vibe Kanban では To Do へ適当に追加しておけばよいのが楽だった
- 例えば、似た構成の複数のパッケージを並列で開発させたあと、それぞれの README.md やコードを見比べて品質の統一をするようなタスクを作成し、次のフェーズへ進む前に実行していた
タスクを簡単に複製できるので、複数の Coding Agent での実装を試したりするのが手軽にできそう
Vibe Kanban ですべてやるよりは CLI や他のツールも適宜使った方がよさそう
試す前はなんとなくスペック駆動との相性が悪そうに思えていたが、使い始めてみるとむしろよいように感じた

Claude Code のステータスラインをカスタマイズする

Mon, 27 Oct 2025 19:57:51 GMT

Copilot CLI を触っていたらブランチ名なんかがいい感じに表示されていて、これを Claude Code でもやりたいと思った。

ステータスラインをカスタマイズする - Claude Code Docs

Claude Code でコンテキストウィンドウの使用状況、コスト、git ステータスを監視するカスタムステータスバーを設定します

docs.claude.com

公式情報の通りに進めることにする。まず、

/statusline

とすると statusline-setup subagent が起動し、.zshrc なんかを確認してなるべく同等のものを構築してくれる。このままでもよいが、自分はターミナルと似ていると一瞬どっちにいるかわからないなと思ったので少しカスタマイズすることにした。

カスタマイズは /statusline にやってほしいことを投げるか、/statusline を実行したあとに普通に会話すればその通りに作ってくれた。

/statusline git status と git diff を確認して、変更があるかと、追加/削除行数をそれぞれ色付きで表示するようにして

最終的にワーキングディレクトリと Git の情報を表示するようにした、どのくらい作業させたかの目安になるので気に入っている:

 /workspaces/reponame [⎇ tmp/branch ↑2↓5] ✗ +4 -3

全部は以下にあるが、自分の欲しいものを Claude Code に作ってもらうほうが良いと思う。

File not found · yaakaito/env

Contribute to yaakaito/env development by creating an account on GitHub.

github.com

DevContainer で Rebuild しても .zsh_history が残るようにする

Mon, 20 Oct 2025 20:33:26 GMT

コンテナを Rebuild する機会はそこまで多くないので、これまで適当に内容をコピペしたりリポジトリ配下に置いたりして誤魔化していたのだが、つらくなってきたの仕組み化しようと思った。履歴は(コンテナの)命より重い・・・・！これまでやってこなかった理由の一つに「リポジトリに含まれる DevContainer の設定に個人の都合を含みたくない」というのがあり、いろいろ方法を考えていたのだが結果としては妥協することにした。

方法は公式にも紹介されているように .devcontainer.json の mounts を使う。これは Claude Code の公式 DevContainer も同じようなことをしていた。

Persist bash history

Persist bash history in containers

code.visualstudio.com

claude-code/.devcontainer/devcontainer.json at main · anthropics/claude-code

github.com

とはいえこのまま使っているわけではなく、もろもろの設定のだるさや保存先が気になったので、ホスト側に XDG Base Directory に沿うような形で配置することにした。

// devcontainer.json
{
    "initializeCommand": "mkdir -p ${localEnv:HOME}/.local/share/devcontainer/${devcontainerId} && touch ${localEnv:HOME}/.local/share/devcontainer/${devcontainerId}/.zsh_history",
    "mounts": [
        "source=${localEnv:HOME}/.local/share/devcontainer/${devcontainerId}/.zsh_history,target=/home/vscode/.zsh_history,type=bind"
    ]
}

これでだいたいリポジトリ毎に履歴が ~/.local/share/devcontainer/{devcontainerId}/.zsh_history へ溜まるようになる。 ${containerEnv:HOME} が使えそうだが Build 時には使えなかった。

これを個人的な設定として devcontainer.local.json のような形で設定できれば理想だったのだがそういった機能は現状ではできないようだ。

.zsh_history 以外にも Claude Code なんかの履歴も同じようにできそうだが、 AI との会話ログにそこまで価値を感じてないのと個人的過ぎるのでやることはないと思う。

Refs

Dev Container metadata reference

The devcontainer.json file contains any needed metadata and settings required to configure a development container for a given well-defined tool and runtime ...

containers.dev

開発コンテナ - Claude Code Docs

一貫性のある安全な環境が必要なチーム向けのClaude Code開発コンテナについて学びます。

docs.claude.com

仕様駆動開発風のオレオレ実装計画を作って AI と併走する

Wed, 15 Oct 2025 00:00:00 GMT

Kiro を皮切りに「仕様駆動開発」が話題になり、最近では Spec Kit のようなフレームワークも登場し、今後何が主流になるか読めない状況だ。自分はツールを変えつつも、Markdown でタスクリストを作って開発するような手法を続けてきていて、現時点でのやり方を振り返りも兼ねて一度まとめておこうと思った。

モチベーション

この方法でやっている理由としては「Cline を主に使っていた頃からこういう手法でやっていたから」というのがほとんどすべてなのだが、細かいところで言うと、

少なくとも Kiro に関しては UI ありきなのが微妙に感じた
最悪コピペで使える規模の小さいプロンプトで完結するようにしたい
要件の入力に汎用性がほしかった(例えば ADR をソースにしたり、都度の会話で行ったり)
自分が直近で扱っていたタスクに関しては、Kiro や Spec Kit のようなフレームワークが提唱するフローは大げさに感じた
仕様駆動開発の各種 md を Git 管理するべきなのかがわかっていなくて、しないのであればフォーマットは自由でよいのではと思った
- これに関しては、自分は「Git 管理したくない」と思っていて、今回もしていない

あたりがある。とはいえ影響を受けていないかというとそうでもなく、タスクリストの作り方に大きく変化があったので、仕様駆動開発風とした、あくまで風である。

また、今のバージョンは以下の影響を大きく受けている:

実用品を作って探る生成AIを使ったソフトウェア開発の現在 - 電通総研テックブログ

みなさんこんにちは、XI本部エンジニアリングオフィスの佐藤太一です。このエントリでは、私がRustで実装したJava用バージョンマネージャであるKopiを紹介すると共に、実装の過程で得た生成AIを使ったソフトウェア開発に関する知見を共有します。 Kopiのソースコードとドキュメントは全てClaude Codeによるものです。私自身は開発環境の構築とメンテナンスをしながら、プロンプトによる指示のみで、約2か月弱の期間に約四万行のRustコードと約六千行のMarkdownを書き上げました。行数の計測においては、コメントや改行は除いています。成果物は全てオープンソースソフトウェアとして公開してい…

tech.dentsusoken.com

AI時代のソフトウェア開発を考える（2025/07版） / Agentic Software Engineering Findy 2025-07 Edition

AI時代のソフトウェア開発を考える（2025/07版）開発生産性 Conference 2025 2025年 7月4日（金） https://dev-productivity-con.findy-code.io/2025

speakerdeck.com

Prompts

3 つのプロンプトを Claude Code の Custom Slash Command として使用している。量が多いものではなく、Claude Code 特有の何かを使うわけでもないので、他のツールでも同様の機能を使ったりコピペで利用できると思う。 1 つ目と 3 つ目はあまり重要ではないので、なくとも良い。

`/dev-plan:new`

あなたはプロのソフトウェアエンジニアです。
これからユーザーが提供するコンテキストをもとにユーザーと議論を行い、コードベースを詳しく分析し、ソフトウェアを設計し、実装計画を立てます。
ユーザーから `/dev-plan:create-md` で作成指示があるまではコードやドキュメントは作成せず、背景、決定、要点、計画をまとめることに徹してください。

開始時に使うプロンプトで、色々書いているが「まだコードを書かないで」ということが伝われば割となんでもよい。 Claude Code の Plan mode だと、何かを相談 → 計画を承認 → コードを書くという流れになってしまい、事前に大きめの決め事をしたい用途とは噛み合わないように思う。

`/dev-plan:create-md`

これまでのコンテキストから実装に必要なタスクリストをコードベースを分析して作成してください。
実装タスクは、このリポジトリ内の実装のみにフォーカスします。

いくつかフェーズに分割し、それぞれが独立し完結したフェーズになるようにしてください。
それぞれのフェーズで実装すべきものや達成すべきゴールを具体的なコードなどを交えて詳しく明記してください。

タスクリストは次のルールに沿って作成します:

- 詳細な行番号は記載せず、ファイル名とシンボルのみで、簡潔に記載
- タスクは twada 氏の TDD の原則に沿って作成
    - RED/GREEN/REFACTOR の prefix はつけない
- テストは 1 ケースづつ実装する、一度に複数のテストを追加することは禁止
- タスクはネストしない

フォーマットは以下です:

```md
# ${title}

## Overview

## Phase N: ${title}

このフェーズで実装すべきものや達成すべきゴールを詳しく明記します。
特にコンテキストから読み取れる設定や数値については具体的に記載します。
実装方針やコード例、技術スタックについても記載します。

### Requirements

EARS記法で次のように要件定義します:

- THE SYSTEM SHALL <応答>.
- WHEN <条件>, THE SYSTEM SHALL <応答>.

### Targets

- ${filename} - ${note}

### Tasks

- [ ] task1
- [ ] task2

### References

- ${filename} - ${note}

## Tech Stack

使用する技術スタックについてまとめます。

## Note

実装にあたって注意するべきことがあれば記載します。
```

ファイルは .dev-plans 以下へ .md 形式で保存してください。

Claude Code と話し合って大体の方針が決まったあとに、計画を Markdown として保存するために使う、今回の話の中心となるもの。ファイルのフォーマットを指定しつつ、適当な実装単位で以下のものをまとめてもらっている:

各フェーズの概要
Requirements - このフェーズで実装するべき要件定義
Targets - 変更対象となるファイル
Tasks - TDD に沿った具体的なタスク
References - 参考にになる情報のあるファイル

Requirements と Tasks セクションが特に重要で、計画をレビューする際はこの 2 つを見ることで想定していないものを作ろうとしていないかを確認している。実際どのようなものになるかは後述する。

`/dev-plan:next`

現在のコンテキストにある .dev-plans 以下の実行計画を参照しながら、実装を行います。
新しい作業を始める前に、前回のタスクがあれば Markdown でチェックリストが完了になっていることを確認してください。

```markdown
- [x] 完了済みタスク
- [ ] 未完了タスク
```

確認したら、未完了の次の $ARGUMENTS を**ひとつだけ**進めてください。完了したら、Markdown のチェックリストを更新してください。

task か phase を引数にとって、それを一つ進める。一つだけじゃ止まらないこともある、可愛いね。もっと細かくコントロールしたい場合などもあるのでなくともよいし、実際使わないこともある。

実際のワークフローの例

個人用に作っている RSS リーダーのクライアント的なものを題材に、「日付ごとに既読にする」機能の追加を作りたいとする。 Claude Code を起動したら、 /dev-plan:new で実装計画の作成を開始する。

> /dev-plan:new is running…

● プロのソフトウェアエンジニアとしてお手伝いします。これからユーザーが提供するコンテキストをもとに、コードベースの分析と設計の議
  論を進めていきます。

  実装計画を立てるために必要な情報を教えてください。以下のような情報があると助かります：

  - 実現したい機能や解決したい課題
  - 背景や動機
  - 現在の問題点
  - 想定しているアプローチやアイデア

  コードベースの分析が必要な場合は、対象となるパッケージやファイルの情報も教えてください。

  /dev-plan:create-md の指示があるまでは、コードやドキュメントは作成せず、設計と計画の議論に集中します。

コードを書かないモードになったら具体的な要件を伝えて、望む要件になるように会話する。別途 ADR のようなものがあったりする場合もここで渡して確認してもらう、なるべくここの汎用性が高くなるようにしたいという意図があってこうなっている。

> @packages/reader に日付ごとに関連する記事を既読にする機能を追加します。\
\
- 各日付セクションの最後に「既読にする」というテキストでボタンを追加する\
- 「既読にする」ボタンを押すと、セクションの内容が既読になり消える\
    - 個別記事をクリックして既読にした場合のコントラスト変更とは異なり、表示しないようにする\
- セクションに記事が一つもないときは「既読にする」ボタンも表示しない

● 了解しました。@packages/reader に日付ごとの記事を一括既読にする機能を追加する計画を立てていきます。

  まず、現在のコードベースの構造を分析させてください。フロントエンドの実装を確認します。

  ......

● 完璧です。コードベースの分析が完了しました。以下、実装計画をまとめます。

  ---
  背景と要件

  実現したい機能

  日付セクションごとに記事を一括既読にする機能を追加します。

  具体的な要件

  1. 各日付セクションの最後に「既読にする」ボタンを配置
  2. ボタンをクリックすると、そのセクションの全記事が既読になり非表示になる
  3. セクションに表示される記事が0件の場合はボタンも表示しない
  4. 個別記事の既読ボタン（コントラスト変更）とは異なり、完全に非表示にする

  ---
  現在の実装の分析

  データ構造

  - 日付でグループ化: GroupedArticlesByDate 型で日付キー（例: "20251013"）ごとに記事を管理
  - 各日付内で2つに分類:
    - withSummary: 要約あり記事をさらにauthor別にグルーピング
    - withoutSummary: 要約なし記事

  ......

  ---
  この計画で問題なければ、/dev-plan:create-md で詳細な実装ドキュメントを作成します。
  質問や修正したい点があれば教えてください。

長いので出力は大きく省略している。ここまでで不透明な部分なんかがあれば質問したりしてくれるはず。今回は通しで実装させるかつテスト周りがわかりやすくなるよう、適当な理由をつけて本来不要な API を新規実装する。

> 機能単位での削除を容易にするため、API は新たに専用のものを作成してください

● 了解しました。専用のAPIエンドポイントを作成するように計画を修正します。

  ---
  設計決定の変更

  新規APIエンドポイント

  決定: /api/articles/read/by-date を新規作成

  エンドポイント仕様

  POST /api/articles/read/by-date
  Content-Type: application/json

  リクエストボディ: string[] (記事IDの配列)

  レスポンス:
  {
    "ids": string[],
    "read": true,
    "feature": "by-date"  // 識別用
  }

  既存の bulk API との違い

  - エンドポイントが分離: 機能ごとに独立したエンドポイント
  - 削除が容易: この機能を削除する際は、このエンドポイントと関連コードのみ削除すればよい
  - 実装は類似: 内部的には同じロジック（記事IDリストを受け取って既読にする）

  ---
  更新された実装計画

  1. バックエンド（backend/index.ts）

  新規エンドポイント追加 (138行目付近、既存のbulk APIの後に追加)

  .post('/api/articles/read/by-date', zValidator('json', z.string().array()), async (c) => {
      // 具体的な実装例
  })

  2. フロントエンド（use-backend.ts）

  新関数追加 (markAsReadAll の後に追加)

  const markAsReadByDate = async (dateKey: string) => {
      // 具体的な実装例
  };

  3. UI実装（app.tsx）

  変更なし（前述の計画通り）

  4. スタイル（app.module.css）

  変更なし（前述の計画通り）

  ---
  機能削除時の手順

  将来この機能を削除する場合：

  1. バックエンド: /api/articles/read/by-date エンドポイントを削除
  2. フロントエンド:
    - use-backend.ts から markAsReadByDate 関数を削除
    - app.tsx から日付セクションのボタンUIを削除
    - app.module.css から .dateMarkAsReadButton を削除

  既存の markAsReadAll や個別既読機能には一切影響しません。

  ---
  この修正で問題なければ、/dev-plan:create-md で実装ドキュメントを作成します。

ここまででやりとりが微妙になってきたな、と思ったら全部ばっさり捨てていて、会話で得た知識で最初のプロンプトを調整している。今回貼り付けているものは 2 回目の結果で、 1 回目はボタンをどこに置くか延々と聞いてくる装置になってしまったので捨てている。

内容に問題がなくなったら /dev-plan:create-md で実装計画を Markdown として保存する。

> /dev-plan:create-md is running…

● 実装計画をドキュメントとして作成します。まず、コードベースをさらに分析して、テストファイルの構造や既存のテストパターンを確認し
  ます。

  ......

● 完璧です。テストの構造も理解できました。それでは実装計画ドキュメントを作成します。

結果としてできた Markdown が以下、Tech Stack や Note 以下はこの解説ではあまり重要ではないので省略している。

# 日付ごとの一括既読機能の実装

## Overview

`reader` パッケージに、日付セクションごとに記事を一括で既読にする機能を追加します。この機能により、ユーザーは特定の日付の記事をまとめて既読にして非表示にできます。

**主な機能要件:**
- 各日付セクションの最後に「既読にする」ボタンを表示
- ボタンをクリックすると、その日付の全記事が既読になり非表示になる
- セクションに表示される記事が0件の場合はボタンも表示しない
- 機能の削除を容易にするため、専用のAPIエンドポイントを作成

**技術スタック:**
- バックエンド: Hono + Cloudflare Workers + D1 Database
- フロントエンド: React + TypeScript
- テスト: Bun test framework + Hono testClient

## Phase 1: バックエンドAPI実装（TDD）

このフェーズでは、日付ごとの一括既読APIエンドポイント `/api/articles/read/by-date` を実装します。既存の `/api/articles/read/bulk` と同様の動作をしますが、機能として独立させることで将来の削除や変更を容易にします。

### Requirements

- THE SYSTEM SHALL 記事IDの配列を受け取り、該当する全記事を既読にする。
- WHEN 記事IDの配列がPOSTされた場合、THE SYSTEM SHALL D1データベースのReadArticleテーブルに記録する。
- WHEN 一部の記事IDが存在しない場合、THE SYSTEM SHALL 存在する記事のみを既読にして201を返す。
- WHEN 全ての記事IDが存在しない場合、THE SYSTEM SHALL 404エラーを返す。
- WHEN 空配列がPOSTされた場合、THE SYSTEM SHALL 404エラーを返す。
- WHEN 無効なデータ型が送信された場合、THE SYSTEM SHALL 400バリデーションエラーを返す。
- WHEN 既読登録が成功した場合、THE SYSTEM SHALL `{ ids: string[], read: true, feature: "by-date" }` の形式でレスポンスを返す。

### Targets

- src/backend/index.ts - 新規エンドポイント `/api/articles/read/by-date` の追加
- src/backend/index.test.ts - 新規エンドポイントのテスト追加

### Tasks

- [ ] POST /api/articles/read/by-date が空のDBで空配列を送信すると404を返すテストを追加
- [ ] POST /api/articles/read/by-date エンドポイントを実装（空配列で404を返す最小実装）
- [ ] POST /api/articles/read/by-date が複数記事を一括既読できるテストを追加
- [ ] 記事IDからArticleを検索し、ReadArticleテーブルに登録する処理を実装
- [ ] POST /api/articles/read/by-date が成功時に正しいレスポンス構造を返すテストを追加
- [ ] レスポンスに `feature: "by-date"` フィールドを含める実装を追加
- [ ] POST /api/articles/read/by-date が部分的に存在しない記事があっても成功するテストを追加
- [ ] 存在する記事のみを処理する実装を確認（既存コードで対応済み）
- [ ] POST /api/articles/read/by-date が全て存在しない記事で404を返すテストを追加
- [ ] 全記事が存在しない場合の404レスポンス処理を確認
- [ ] POST /api/articles/read/by-date が無効なデータ型でバリデーションエラーを返すテストを追加
- [ ] zodバリデーションの追加（`z.string().array()` を使用）
- [ ] POST /api/articles/read/by-date で一括既読後にGET /api/articlesで全てisRead: trueになるテストを追加
- [ ] エンドツーエンドの動作確認（既存のReadArticleテーブルとの連携）

### References

- src/backend/index.ts:138-173 - 既存の `/api/articles/read/bulk` エンドポイント（実装パターンの参考）
- src/backend/index.test.ts:236-321 - 既存の一括既読機能のテスト（テストパターンの参考）
- src/backend/test/fixtures/test-data.ts - テストデータのセットアップ
- src/backend/test/mocks/d1.ts - D1データベースのモック実装

## Phase 2: フロントエンド状態管理実装

このフェーズでは、`use-backend.ts` に日付ごとの一括既読処理を行う `markAsReadByDate` 関数を追加します。この関数は、指定された日付キーに対応する全記事を既読にし、楽観的更新とエラーハンドリングを提供します。

### Requirements

- THE SYSTEM SHALL 日付キー（例: "20251013"）を受け取り、その日付の全記事を既読にする。
- WHEN 日付キーが存在しない場合、THE SYSTEM SHALL 処理を中断する。
- WHEN 記事が0件の場合、THE SYSTEM SHALL 処理を中断する。
- THE SYSTEM SHALL 楽観的更新により即座にUIを更新する。
- WHEN API呼び出しが失敗した場合、THE SYSTEM SHALL 状態をロールバックする。
- THE SYSTEM SHALL pending既読状態もクリアする。
- THE SYSTEM SHALL 新規APIエンドポイント `/api/articles/read/by-date` を呼び出す。

### Targets

- src/frontend/component/use-backend.ts - `markAsReadByDate` 関数の追加

### Tasks

- [ ] `markAsReadByDate` 関数のスケルトンを追加
- [ ] 日付キーから `groupedArticles[dateKey]` を取得する処理を実装
- [ ] `withSummary` の全author配下の記事IDを収集する処理を実装
- [ ] `withoutSummary` の記事IDを収集する処理を実装
- [ ] 記事IDが0件の場合に早期リターンする処理を追加
- [ ] 楽観的更新により `readOnThisSession` を更新する処理を実装
- [ ] `pendingReadOnThisSession` から該当記事を削除する処理を実装
- [ ] `/api/articles/read/by-date` APIを呼び出す処理を実装
- [ ] API失敗時の状態ロールバック処理を実装
- [ ] エラーログ出力処理を追加
- [ ] `useBackend` の戻り値に `markAsReadByDate` を追加

### References

- src/frontend/component/use-backend.ts:146-171 - 既存の `markAsReadAll` 関数（実装パターンの参考）
- src/frontend/component/use-backend.ts:21-69 - `groupedAndSorted` 関数（データ構造の参考）
- src/frontend/component/use-backend.ts:98-115 - `markAsRead` 関数（エラーハンドリングの参考）

## Phase 3: UI実装とスタイリング

このフェーズでは、各日付セクションに「既読にする」ボタンを追加し、適切なスタイルを適用します。表示される記事が0件のセクションではボタンを表示しないようにします。

### Requirements

- THE SYSTEM SHALL 各日付セクションの最後に「既読にする」ボタンを表示する。
- WHEN セクション内のフィルタ後の記事が0件の場合、THE SYSTEM SHALL ボタンを表示しない。
- WHEN ボタンがクリックされた場合、THE SYSTEM SHALL `markAsReadByDate` 関数を呼び出す。
- THE SYSTEM SHALL 既存の `.toggleButton` と統一感のあるスタイルを適用する。
- THE SYSTEM SHALL ボタンに適切なマージンを設定し、視覚的に分かりやすく配置する。

### Targets

- src/frontend/component/app.tsx - 日付セクションへのボタン追加
- src/frontend/component/app.module.css - ボタンスタイルの追加

### Tasks

- [ ] 日付セクション内のフィルタ後記事数をカウントする処理を追加
- [ ] `withSummary` の全author配下のフィルタ済み記事数を計算
- [ ] `withoutSummary` のフィルタ済み記事数を計算
- [ ] 記事数が0より大きい場合のみボタンを表示する条件分岐を追加
- [ ] 「既読にする」ボタンの要素を追加（`button` タグ）
- [ ] ボタンのクリックハンドラに `markAsReadByDate(key)` を設定
- [ ] app.module.css に `.dateMarkAsReadButton` クラスを追加
- [ ] ボタンの基本スタイル（色、パディング、ボーダー）を設定
- [ ] ボタンのホバースタイルを追加
- [ ] ボタンの配置用マージンを設定（日付セクション内で適切に配置）

### References

- src/frontend/component/app.tsx:59-94 - 既存の日付セクションレンダリング
- src/frontend/component/app.tsx:96-103 - 既存のコントロールボタン
- src/frontend/component/app.module.css:58-77 - 既存の `.toggleButton` スタイル
- src/frontend/component/app.tsx:43-55 - `filterArticle` 関数

## Phase 4: 統合テストと動作確認

このフェーズでは、実装した機能が正しく動作することを確認します。特に、日付セクションごとの既読処理が適切に動作し、UIが期待通りに更新されることを検証します。

### Requirements

- THE SYSTEM SHALL 開発環境で全ての機能が正常に動作する。
- THE SYSTEM SHALL 日付セクションのボタンをクリックすると、そのセクションの記事が非表示になる。
- THE SYSTEM SHALL ボタンクリック後、セクション自体も非表示になる（記事が0件になるため）。
- THE SYSTEM SHALL 他の日付セクションに影響を与えない。
- THE SYSTEM SHALL エラーケースで適切にロールバックする。

### Targets

- 全実装コード
- 開発環境でのブラウザ動作確認

### Tasks

- [ ] バックエンドのユニットテストを全て実行（`bun test src/backend/index.test.ts`）
- [ ] テストが全てパスすることを確認
- [ ] ビルドが成功することを確認（`bun run build`）
- [ ] 開発サーバーを起動（`bun run dev`）
- [ ] ブラウザで複数日付の記事が表示されることを確認
- [ ] 最新日付の「既読にする」ボタンが表示されることを確認
- [ ] ボタンをクリックして、その日付の記事が非表示になることを確認
- [ ] 他の日付セクションが影響を受けないことを確認
- [ ] ページをリロードして、既読状態が永続化されていることを確認
- [ ] Chrome拡張機能をビルド（`bun run build-extension`）
- [ ] Chrome拡張機能で同様の動作確認
- [ ] biomeによるコード品質チェック（`bunx @biomejs/biome check --apply ./`）

### References

- CLAUDE.md:13-38 - ビルド・開発コマンドの一覧
- packages/reader/README.md - Reader パッケージのドキュメント（もし存在する場合）

## Tech Stack

......

## Note

### 実装上の注意点

......

Markdown ができたら、この内容を詳しくレビューする。特に Requirements と Tasks セクションを重点的に見て、想定したものになっているかを確認する。例えば以下のようなものがあれば調整する:

仕様の不足 / 不要な仕様が混じっている → 仕様、要件の軌道修正
タスクの粒度が大きすぎる → 1 タスクを自身がレビューしやすいと思われるサイズに調整
テストが足りていない → 書いてほしいテストを指示し追加
実装の順番が不適切 → タスクの順番を入れ替えを指示、大きく変えるときは直接編集して読み込み直す

> - WHEN 既読登録が成功した場合、THE SYSTEM SHALL `{ ids: string[], read: true, feature: "by-date" }` の形式でレスポンスを返す。\
\
read: true と feature フィールドは不要です

● 承知しました。レスポンス形式を { ids: string[] } のみに修正します。

● Update(.dev-plans/mark-as-read-by-date.md)
  ⎿  Updated .dev-plans/mark-as-read-by-date.md with 1 addition and 1 removal
       27    - WHEN 全ての記事IDが存在しない場合、THE SYSTEM SHALL 404エラーを返す。
       28    - WHEN 空配列がPOSTされた場合、THE SYSTEM SHALL 404エラーを返す。
       29    - WHEN 無効なデータ型が送信された場合、THE SYSTEM SHALL 400バリデーションエラーを返す。
       30 -  - WHEN 既読登録が成功した場合、THE SYSTEM SHALL `{ ids: string[], read: true, feature: "by-date" }` の形式でレスポンスを返す。
       30 +  - WHEN 既読登録が成功した場合、THE SYSTEM SHALL `{ ids: string[] }` の形式でレスポンスを返す。
       31
       32    ### Targets
       33

● Update(.dev-plans/mark-as-read-by-date.md)
  ⎿  Updated .dev-plans/mark-as-read-by-date.md with 1 removal
       41    - [ ] POST /api/articles/read/by-date が複数記事を一括既読できるテストを追加
       42    - [ ] 記事IDからArticleを検索し、ReadArticleテーブルに登録する処理を実装
       43    - [ ] POST /api/articles/read/by-date が成功時に正しいレスポンス構造を返すテストを追加
       44 -  - [ ] レスポンスに `feature: "by-date"` フィールドを含める実装を追加
       44    - [ ] POST /api/articles/read/by-date が部分的に存在しない記事があっても成功するテストを追加
       45    - [ ] 存在する記事のみを処理する実装を確認（既存コードで対応済み）
       46    - [ ] POST /api/articles/read/by-date が全て存在しない記事で404を返すテストを追加

● 修正完了しました。以下の変更を行いました：

  1. Requirementsセクション（30行目）: レスポンス形式を { ids: string[] } のみに変更
  2. Tasksセクション（46行目）: feature: "by-date" フィールド追加タスクを削除

  これで、APIレスポンスは既存の /api/articles/read/bulk と同じシンプルな形式になります。実装がよりシンプルになりますね。

調整が終わったら、一度 Claude Code を終了して、実装計画だけを読み込み直している。Git 管理していない場合は補完が効かず少しめんどくさい。読み込んだあとは /dev-plan:next phase や都度の指示で、計画が完了するまで順番に消化していく。

> Read @.dev-plans/mark-as-read-by-date.md

● ファイルを確認しました。これは日付ごとの一括既読機能の実装計画書ですね。内容を要約します：

  📋 実装計画の概要

  ......

  ---
  次のステップ: Phase 1から順番に実装を進めますか？それとも特定のフェーズについて詳しく確認したいことがありますか？

> /dev-plan:next phase

基本的には Manual Accept で進め、特にテストコードは都度細かく確認するように意識している。自分しか使わない UI の構築タスクなんかは Auto Accept で進めることもあるが、そもそもこの手法を採用するのは、自分の頭にあるコードを高速に書くツールとして AI を利用したいようなケースなので、 Auto Accept すること自体にあまり意味がないと考えている。

雑感

ある程度規模のあるタスクを一元管理できるようになり、出力も安定しているように思うので、比較的安心してコードを生成できている肌感はある
一方で現状タスクやフェーズのゴールの定義が曖昧だなと感じていて、直近で Codex のイベントで紹介されていた方法は参考なりそうだが、まだ見れていない: https://www.youtube.com/watch?v=Gr41tYOzE20
この手法で時間という意味での生産性があがるのかと言われると微妙で、結局計画をレビューするのに時間とスタミナを使ってしまう、最後の 10% (＝実際のコード生成) だけを見れば速いと思う
- 慣れの問題だったり、記述するべきコードの量が多い場合は時間が短縮できるようには思う
結局実装計画のようなものを Git 管理に乗せるべきなのかはよくわからない
基本的にはこの形になっていたからか、少なくとも手元では Claude Code の性能の劣化、みたいなのをあまり感じなかった
ファイルを Git 管理しない場合に Claude Code では補完が効かないのが不便
- この辺は Issue になっている: https://github.com/anthropics/claude-code/issues/5105
- .git 以下に置くのもためしたが、こちらは補完は効くが相談中に Auto Accept で複数行修正したいようなケースでそれが効かなくて不便、特別な権限が設定されている？
この手法を続けるかは現時点ではわからないが、Spec Kit はしばらく使ってみたいと思っている

dependabot の cooldown と pnpm/bun の minimumReleaseAge を設定する

Sun, 28 Sep 2025 16:37:18 GMT

直近で話題になることが多かったサプライチェーン攻撃に対する予防策として、「一定時間経過したパッケージしかアップデート対象にしない」というオプションが dependabot や pnpm に導入されている。

Dependabot supports configuration of a minimum package age - GitHub Changelog

The cooldown feature is now generally available for Dependabot version updates! This feature gives you control over when version update pull requests are created to bump your dependencies. What’s new…

github.blog

pnpm 10.16

pnpm.io

pnpm 10.17

pnpm.io

dependabot / cooldown

Dependabot バージョン更新プログラムに合わせて pull request の作成を最適化する

docs.github.com

.github/dependabot.yml に次のように設定する:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/workers"
    schedule:
      interval: weekly
    cooldown:
      default-days: 7
      semver-major-days: 14

semver-major-days などで semantic versioning に従って細かく設定ができる。include / exclude での除外設定もサポートされている。

pnpm / minimumReleaseAge

Settings (pnpm-workspace.yaml)

pnpm.io

pnpm-workspace.yaml に次のように設定するか、CLI からも設定できる:

minimumReleaseAge: 10080

$  pnpm config set --location=project minimumReleaseAge 10080

dependabot とは違い、こちらは分単位での指定(7日)。 10.17.0 で minimumReleaseAgeExclude が入って除外設定もできるようになった。

[追記] bun / minimumReleaseAge

bunfig.toml - Bun

Configure Bun's behavior using its configuration file bunfig.toml

bun.com

bunfig.toml で設定する:

[install]
minimumReleaseAge = 604800
minimumReleaseAgeExcludes = ["@types/bun"]

これは秒になっていてややこしい…。pnpm の 60 倍になっているが、設定としてはこれで同じ。

bun:sqlite を使って bun test で Hono + Cloudflare Workers + D1 をテストする

Tue, 09 Sep 2025 12:04:41 GMT

Cloudflare D1 を bun:sqlite で代用することで、 wrangler を使わずに bun test でテストが書けるようにした。ORM も使っていないような簡単なアプリ向け。

まず、 bun:sqlite をオンメモリで作成して、必要なテーブルを用意しつつ D1 互換のインターフェイスを返すモックを作れるようにする。

import { Database } from 'bun:sqlite';

export function createMockD1Database() {
    const db = new Database(':memory:');

    db.exec('BEGIN');
    db.exec(`
        CREATE TABLE ...
    `);
    db.exec('COMMIT');

    return {
        prepare: (query: string) => {
            const stmt = db.prepare(query);

            return {
                bind: (...params: any[]) => ({
                    all: async () => {
                        try {
                            const results = stmt.all(...params);
                            return {
                                results,
                                success: true,
                                meta: {},
                            };
                        } catch (error: any) {
                            return {
                                results: [],
                                success: false,
                                meta: { error: error.message },
                            };
                        }
                    },
                    first: async () => {
                        try {
                            return stmt.get(...params) || null;
                        } catch (error) {
                            return null;
                        }
                    },
                    run: async () => {
                        try {
                            stmt.run(...params);
                            return {
                                success: true,
                                meta: {
                                    changes: db.changes,
                                    last_row_id: db.lastInsertRowid,
                                },
                            };
                        } catch (error: any) {
                            return {
                                success: false,
                                meta: { error: error.message },
                            };
                        }
                    },
                }),
            };
        },

        batch: async (statements: any[]) => {
            const results = [];
            for (const statement of statements) {
                const result = await statement.run();
                results.push(result);
            }
            return results;
        },

        exec: (sql: string) => {
            return db.exec(sql);
        },
    };
}

このモックを Hono の testClient で DB として渡すことで、 D1 の代わりにモックが使用され、他のツールなしに bun test でテストが書ける。

describe('Tests', () => {
    let client: TestClient;
    let mockDB: ReturnType<typeof createMockD1Database>;

    beforeEach(() => {
        mockDB = createMockD1Database();
        client = testClient(app, {
            DB: mockDB,
        });
    });

    test('api', async () => {
        const res = await client.api.items.$get();
        expect(res.status).toBe(200);

        const items = await res.json();
        expect(Array.isArray(items)).toBe(true);
        expect(items).toHaveLength(0);
    });
})

事前にテストデータなんかがほしいときは普通に mockDB.exec を使って入れたりしている。

Refs

Testing Helper - Hono

Web framework built on Web Standards for Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Node.js, and others. Fast, but not only fast.

hono.dev

GitHub - yusukebe/testing-d1-app-with-types: Testing a D1 Application with Types

Testing a D1 Application with Types. Contribute to yusukebe/testing-d1-app-with-types development by creating an account on GitHub.

github.com

SQLite - Bun

Bun natively implements a high-performance SQLite3 driver.

bun.com

ES Module の import defer

Fri, 22 Aug 2025 11:59:48 GMT

TypeScript 5.9 の告知を見て知ったのだが、 import はするがその評価を遅延する、という構文が ES の Stage 3 になっている。

Announcing TypeScript 5.9 - TypeScript

Today we are excited to announce the release of TypeScript 5.9! If you’re not familiar with TypeScript, it’s a language that builds on JavaScript by adding syntax for types. With types, TypeScript makes it possible to check your code to avoid bugs ahead of time. The TypeScript type-checker does all this, and is also the […]

devblogs.microsoft.com

GitHub - tc39/proposal-defer-import-eval: A proposal for introducing a way to defer evaluate of a module

A proposal for introducing a way to defer evaluate of a module - tc39/proposal-defer-import-eval

github.com

従来 import や require と同時に大きな副作用なあるようなモジュールを読み込む際、それを実際に使用するまで読み込みを遅延するようなテクニックがあった。例えば、 require を使った次のようなコードである（ Proposal からの引用）:

// https://github.com/tc39/proposal-defer-import-eval/?tab=readme-ov-file#motivation
exports.doSomething = function (target) {
  const operation = require('operation');
  return operation(target);
}

これを解決するスマートな構文として次のようなものが提案されている（ Proposal からの引用）:

// https://github.com/tc39/proposal-defer-import-eval/?tab=readme-ov-file#proposal
import defer * as yNamespace from "y";

頻度はそう高くないが、 ESM で書いている場合に require の例のような記述をすることは諦めていたので、なるほどなぁとなる提案だった。

2025年7月版個人的開発スタイル with Claude Code

Tue, 15 Jul 2025 00:00:00 GMT

最近の開発はほとんど Claude Code で行っているが、使い始めた 3 月から比べると利用スタイルも結構変わったなとふと思ったので、あとで懐かしむために今やっているスタイルを書き残すことにした。個人的な開発に使っているもので、業務にこのフローを適用しているわけではないのと、Claude Code でうまくコードを書く方法ではなくその周辺の話。

全体感

開発は Dev Containers もしくは GitHub Codespaces
ローカル開発では VSCode でメインの Claude Code + git worktree でいくつかの並列作業
- GitHub Copilot もたまに使う
Claude Code Actions でレビューと GitHub Issues の分析
- レビューは CodeRabbit も使っている
HACK 的な設定は入れない
コンテキストを充実させて解決することを意識する

Dev Containers / Codespaces での開発

数年前に個人的な開発はすべてこれらに移行している。この地点からの変化として AI 系のツールの準備をどこで行うか、というのがあって今はいわゆる dotfiles(envというリポジトリにしている) 側で管理していて、setup.sh の流れの中で Claude Code をインストールしている。

env にはいくつか Claude Code を便利に使うための設定やツールを含んでいて、自分の管理するどのリポジトリでも使えるようになっている。特に影響の大きいものだと全体の CLAUDE.md つまり ~/.claude/CLAUDE.md に日本語で出力するよう設定している。

## YOU MUST

- ユーザーの入力に使用された言語にかかわらず、日本語で返答やコードの出力を行います
- Git Commit や Pull request を作成する際、指示がなければ日本語で内容を作成します

## IMPORTANT

- git commit を行うときは、指示がなければ [commit.md](~/.claude/commands/commit.md) のルールに従ってください

加えて、全体の settings.json として、Read 系だったり、比較的安全なコマンドを許可している。issue なんかは価値観によるかもしれない。

{
    "permissions": {
        "allow": [
            "Bash(cat:*)",
            "Bash(cp:*)",
            "Bash(find:*)",
            "Bash(head:*)",
            "Bash(gh api:*)",
            "Bash(gh issue create:*)",
            "Bash(gh issue edit:*)",
            "Bash(gh pr diff:*)",
            "Bash(gh pr list:*)",
            "Bash(gh pr view:*)",
            "Bash(git add:*)",
            "Bash(git branch:*)",
            "Bash(git log:*)",
            "Bash(git push:*)",
            "Bash(git rm:*)",
            "Bash(grep:*)",
            "Bash(ls:*)",
            "Bash(mkdir:*)",
            "Bash(mv:*)",
            "Bash(rg:*)",
            "Bash(tail:*)",
            "Bash(xargs grep:*)",
            "Read(~/.claude/commands/commit.md)"
        ]
    }
}

細かいツールやコマンドなんかはそれぞれが登場するときにまた紹介する。

ローカルの Claude Code での開発

Claude Code は基本的に VSCode の Terminal で動作させているが、連携の拡張機能は使っていない。最近は「Create New Terminal in Editor Area」でファイルなどと同じエディター領域で開いてしまって、そこで Claude Code を実行している。自分がターミナルとして操作したい場合は、これまで通りの Terminal を使ったり、同じようにエディター領域で開いたりとその時の気分でやっている。

画面としてはこんな感じで作業している:

青い部分がメインの Claude Code のエリアで、ここでは Claude Code と対話しながら進めたい変更を行う。基本的に 1 ラインしか動くことはない。コアになる機能の開発なんかはここで行っている。

赤い部分はメインの変更点を Git diff で見る、もしくはサブタスクを Claude Code で並列しながら行う場合にそのターミナルをタブで出していて、これについては後述する。Git diff は VSCode についているソース管理のビューを使っていて、変更点をまとめて開くことが出来るので Claude Code が書いた内容をレビューするのに重宝している。このビューは worktree にも対応していて、裏でやっていた作業をまとめて確認する場合にも役立つ。

緑の部分は普通にエクスプローラーや検索を使う。VSCode がいろいろ機能がついていて便利なターミナルと化している気がしなくもない。

いわゆる右側の AI パネルは最近はほとんど使うことがなくなってしまったが、GitHub Copilot を使うときには出てきたりする。Copilot は主に、コンテキストの指定が面倒な JSX や CSS を範囲指定で渡して何かしらをしてもらう用途に使っている。Copilot 用の設定は特に入れていない。

git worktree を使った並列作業

そこまで対話が必要なく、ある程度の指示があれば Claude Code が自走できるものは git worktree を使って裏で作業させている。これをローカルの Claude Code でやっている理由は GHA で Max プランが適用されないからなのだが、最近適用出来るようになったので GHA で間に合うものはなるべくそちらで済ますようにしている。アイデアはあるけど一度やらせてみてどうなるか見てみたい、というものは結構あるので、そういった中規模程度のタスクを一度やらせてみるのがメインな使い方になっているかもしれない。

実際の使い方については GitHub Issues を起点にしている。 env リポジトリに以下の流れを行うスクリプトを用意していて、実行すると worktree で実装が始まる。

Issue の一覧を peco で表示
選択した Issue とコメントの内容を取得
Issue の内容から branch 名を生成
branch 名で branch と worktree を作成
worktree のディレクトリへ移動し、.env のコピーや依存関係の準備をする
Issue から prompt を作って、 claude --dangerously-skip-permissions で実行

この一連の流れが以下のコマンドで実行できるようにしている:

$ resolve-issue

実際に使うときは新しいターミナルを開いて上記のコマンドを実行するという感じ。worktree は .git/working-trees 以下に入れるようにしていて、こうしておくと管理が楽なのと、 VSCode のソース管理で Diff が見れるというメリットがある。

Claude Code Actions での Issue 作成のサポート

Issue をベースにするので当然 Issue を作る必要があるのと、あまりに内容があれだとうまくいかない。-p オプションで実行しているわけではないので、都度指示を継ぎ足したりすることも出来るが、基本的には Issue の内容をある程度書く形でやっている。これを補助するために Issue に対して GHA で Claude Code Actions を実行して、Issue の内容を分析したり、レビューを行うようにしている。

- uses: anthropics/claude-code-action@beta
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    github_token: ${{ secrets.GITHUB_TOKEN }}
    direct_prompt: |
        Issueとコメントの内容を確認し、コードベースをもとに実装は行わず分析して、実装計画を考えてください。
        その後、考えた実装計画から以下の点をユーザーにフィードバックしてください。
        - 変更内容の3行程度のサマリー
        - 主に変更されるファイルと変更内容
        - 不足している情報をユーザーに質問
        英語で考えて、最終的なアウトプットだけ日本語で出力してください。

これで自分がわかっていない変数を AI に補完してもらったりして Issue を完成させている。Claude Code からのコメントが残り続けるとプロンプトになったときにノイズになりそうなので、 Issue の内容に満足したらコメントは削除するようにしている。実装できそうであればそのまま @claude で実装してもらうこともある。

以前は料金が気になって一部のものだけをラベルでトリガーしていたが、 Max プランが GHA にも適用できるようになってとりあえずこれを流しておけるようになったので便利。

リモートの Claude Code Actions での開発

ほとんど書いてしまったようなものだが、Max プランで動かせるようになってからは小さなタスクは積極的に @claude で実装を行ってもらっている。欠点として修正がいくつが必要な場合に PR が荒れがちになるというのがある。適当に見切りをつけてローカルでの実行に移行したいとは思っているが、このあたりはまだこれといって方針は見えていない。

Claude Code の設定

ざっくり言えば、

CLAUDE.md は /init で作成したものに日本語使用することだけを付け足している
- 明らかに操作が変わったときは合わせて更新している
Permissions はそれぞれのリポジトリに合わせて build test lint など普段の操作を許可している
うまく開発を回すためにいくつか Custom Slash Command を作ったり Hook を設定したりしている

基本的にはあまり Claude Code 自体はカスタマイズはせずに、都度コンテキストを渡すことを意識している。

Custom Slash Command

リポジトリ単位で作っているものと、共通で使っているものがある。リポジトリ単位では、複雑になりがちなフローをまとめたりしている。例えば以下は playwright で Chrome 拡張のテストを実行するためのフローをまとめたもの:

---
allowed-tools: Bash(bun run build), Bash(bun run build-extension), Bash(bun run e2e)
description: Run end-to-end tests for the @repo/reader package with proper setup.
---

# Run E2E Tests

Run end-to-end tests for the @repo/reader package with proper setup:

1. Navigate to reader package: `cd /workspaces/repo/packages/reader`
2. Build web application: `bun run build`
3. Build Chrome extension: `bun run build-extension`
4. Run E2E tests: `bun run e2e`
5. Check screenshots in `screenshots/` directory

Show progress for each step and report test results with any failures highlighted.

共通のコマンドとして env に以下のようなものを用意している、お気に入りは workflow-fix。

/commit - コミットメッセージにここまでの AI とのやりとりを含めてコミットする
/reviews-fix - 現在のブランチに対応する PR のレビューコメントを集めて修正を行う
/workflow-fix - 現在のブランチに対応するワークフローを確認し、失敗していたら修正を行う
/workflow-fix-file - 指定したファイル名のワークフローを確認し、失敗していたら修正を行う

この辺りはリポジトリに依存しない、個人の開発スタイルだと考えて共通にしているが、/commit は怪しい。例えば /create-pr はリポジトリごとにある程度ルールが存在するはずなので共通にすることはないというのがわかりやすいが、このあたりの区別はまだまだ曖昧。それと、共通のものは workflow-fix のように workflow や reviews を前にしている、数が多くなったときにこの方が絞り込みがしやすいように思う。

Hooks

編集時の format 、 commit 前の test と lint を設定しているのと、リポジトリに合わせて「bun を使っているのに npm を使おうとするのを止める」のような明らかな間違いを止める Hooks を設定している。

{
    "hooks": {
        "PostToolUse": [
            {
                "matcher": "Write|Edit|MultiEdit",
                "hooks": [
                    {
                        "type": "command",
                        "command": "jq -r '.tool_input.file_path | select(endswith(\".js\") or endswith(\".ts\") or endswith(\".jsx\") or endswith(\".tsx\")) or endswith(\".json\")) or endswith(\".css\"))' | xargs -r bun biome format --write"
                    }
                ]
            }
        ],
        "PreToolUse": [
            {
                "matcher": "Bash",
                "hooks": [
                    {
                        "type": "command",
                        "command": "jq -r '.tool_input.command // \"\"' | grep -q \"^git commit\" && (bun run lint 1>/dev/null; [ $? -eq 1 ] && echo '{\"decision\":\"block\",\"reason\":\"Lint errors found. Fix them before committing.\"}' && exit 2) || true"
                    },
                    {
                        "type": "command",
                        "command": "jq -r '.tool_input.command // \"\"' | grep -q \"^git commit\" && (bun run test 1>/dev/null; [ $? -eq 1 ] && echo '{\"decision\":\"block\",\"reason\":\"Tests failed. Fix them before committing.\"}' && exit 2) || true"
                    },
                    {
                        "type": "command",
                        "command": "jq -r '.tool_input.command // \"\"' | grep -qE \"^(npm|npx)\\s\" && echo '{\"decision\":\"block\",\"reason\":\"Consider using bun instead of npm/npx for better performance. Examples: npm install → bun install, npm run → bun run, npx → bun x\"}' && exit 2 || true"
                    },
                    {
                        "type": "command",
                        "command": "jq -r '.tool_input.command // \"\"' | grep -qE \"^bunx @biomejs/biome check\" && echo '{\"decision\":\"block\",\"reason\":\"Use bun biome lint instead of bunx @biomejs/biome check for better performance and consistency.\"}' && exit 2 || true"
                    }
                ]
            }
        ]
    }
}

Pull request のレビュー環境

ローカルの Claude Code で作ったものと、Claude Code Actions で作ったものでフローが異なる。

前者はコードレビューだけ行っていて、Claude Code Actions と CodeRabbit、たまに GitHub Copilot を使っている。レビューされた内容は、web 上で不要なものは Resolve したりしつつ、前述の /reviews-fix を使って修正を行っている。

後者の Claude Code Actions で作成したコードは、ローカルの開発環境を経由せずにマージまで持っていきたかったので、作れるものに関しては Cloudflare の Preview URLs を使って確認用の環境を作ってみている、そうでないものは Codespaces で起動したりとか。

Preview URLs

Preview URLs allow you to preview new versions of your project without deploying it to production.

developers.cloudflare.com

Claude Code Actions ないしリモートの AI (コンテナ) で作られたものの動作をどう確認するのかというのは課題感としてあり、特に出力に AI が絡むものはテストコードなどでは保証が難しいのをどうしていくのがいいかあまりわかっていない。

雑感

個々のリポジトリで多少の違いはありつつも、全体的には Claude Code と GitHub Issues を中心に据えたスタイルになってきているように思う。自分は積極的にコードが書きたいとかコード書いて楽しいと思っているタイプではないのもあり、モチベが低くとも一旦雑にでも Issue にさえしてしまえば、手をつけられる環境に近づいたことに価値を感じている。

やりたいと考えてはいるがうまくできていない、まだやっていないことを書き残して終わる。

人間と AI 向けのドキュメントを Markdown で残すようにしているものの AI が書くとどうしても淡々とした説明になってしまう、 Why を残すのであれば人間がうまく挟まる必要がありそう
gemini-cli も導入して、 Issue に対して評価を行う際に Gemini と話し合ってほしい
PR レビューが Bot で荒れがちになるのを整理したいが特にアイデアはなし

Claude Code の Hook で format lint test を実行する

Thu, 10 Jul 2025 11:18:18 GMT

Claude Code に追加された Hook 機能を使って、これまで CLAUDE.md や githooks で実現していたツールの実行を Claude Code の設定に移してみる。format は公式でも利用例として紹介されている。

Hooks reference - Claude Code Docs

Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks.

docs.anthropic.com

今回は format は編集時 PostToolUse 、lint と test は git commit の PreToolUse で実行したいと考え、最終的には次のように設定した:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path | select(endswith(\".js\") or endswith(\".ts\") or endswith(\".jsx\") or endswith(\".tsx\")) or endswith(\".json\")) or endswith(\".css\"))' | xargs -r bun biome format --write"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command // \"\"' | grep -q \"^git commit\" && (bun run lint 1>/dev/null; [ $? -eq 1 ] && echo '{\"decision\":\"block\",\"reason\":\"Lint errors found. Fix them before committing.\"}' && exit 2) || true"
      }, {
        "type": "command",
        "command": "jq -r '.tool_input.command // \"\"' | grep -q \"^git commit\" && (bun run test 1>/dev/null; [ $? -eq 1 ] && echo '{\"decision\":\"block\",\"reason\":\"Tests failed. Fix them before committing.\"}' && exit 2) || true"
      }]
    }]
  }
}

format と lint には biome を使っていて、 test は monorepo でパッケージごとに異なるツールを利用している。設定のポイントとして、例えば biome lint の Lint Error は Exit code が 1 なのでそのままでは git commit が止まらない。そのため PreToolUse では、コマンドがエラーだったときに詳細な JSON と Exit code 2 を返すようにしている。少し読みやすくするとこうなる:

jq -r '.tool_input.command // \"\"' | grep -q \"^git commit\"
    && (bun run lint 1>/dev/null; 
        [ $? -eq 1 ] 
        && echo '{\"decision\":\"block\",\"reason\":\"Lint errors found. Fix them before committing.\"}'
            && exit 2)
|| true

これで今のところうまく動いているよう見える。これが便利かはまだ体感できていないので、すぐにやめる可能性はある。

Claude Code の PreToolUse Hook で誤ったパッケージマネージャーの利用を止める

Thu, 10 Jul 2025 11:09:07 GMT

Claude Code に追加された Hook 機能を使って「bun を利用しているのに npm を使おうとする」というような動作を防止することが出来そうだったので試した。

Hooks reference - Claude Code Docs

Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks.

docs.anthropic.com

PreToolUse では設定されたコマンドが exit code 2 を返すと、実行しようとしていたツール利用をブロックすることができる。さらに JSON で詳しい情報を伝えることで Claude Code が必要なリカバリを行うため、これに合わせて次の設定を試した:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command // \"\"' | grep -qE \"^(npm|npx)\\s\" && echo '{\"decision\":\"block\",\"reason\":\"Consider using bun instead of npm/npx for better performance. Examples: npm install → bun install, npm run → bun run, npx → bun x\"}' && exit 2 || true"
      }]
    }]
  }
}

少し読みやすくするとこんな感じ:

jq -r '.tool_input.command // \"\"' | grep -qE \"^(npm|npx)\\s\" &&
    echo '{
         \"decision\":\"block\",
         \"reason\":\"Consider using bun instead of npm/npx for better performance. Examples: npm install → bun install, npm run → bun run, npx → bun x\"
    }' && exit 2
|| true

雑ではあるが、これで誤った npm の実行をブロックすることができた。

Biome v2 の GritQL での Linter Plugins を試す

Wed, 25 Jun 2025 13:50:37 GMT

Biome v2 がリリースされ、β 版の機能として Linter Plugins が追加された。

Biome v2—codename: Biotype

biomejs.dev

Linter Plugins

biomejs.dev

実装は GritQL によるパターンマッチングをベースに作られていて、現状 Fix はできず検出のみとなっている。

Grit - Declarative Code Search and Transformation

docs.grit.io

まだ β 版という前提はありつつも、 ESLint でやっているような Monorepo 内での期待しない import の検出ができれば乗り換え¹ができるなと思い、以下のようなルールを試した。

or {
    `import $_ from $path`,
    `import { $_ } from $path`,
    `import * as $_ from $path`,
} where {
    $path <: `'@project/theModule'`,
    register_diagnostic(
        span = $path,
        message = "このパッケージから theModule へ依存することは出来ません。",
        severity = "error"
    )
}

これを同じく v2 で追加された Monorepo サポートと兼用しパッケージ事に設定することで、泥臭いながらも期待するものはある程度実現できる。ただ、Side Effect Import の場合にうまくいかず、以下が動作うまくしなくてハマっていた。

`import $path` where {
    $path <: `'@project/theModule'`,
    register_diagnostic(
        span = $path,
        message = "このパッケージから theModule へ依存することは出来ません。",
        severity = "error"
    )
}

$path 周りの記述の仕方をいくつか試したが、 biome search でもマッチングがうまくいかなかった。

$ npx biome search '`import $path`' 
Searched 57 files in 95ms. Found 0 matches.

一方で以下は動作するので、単純に実装が間に合っていないだけなのかもしれないが詳しくは調べていない。

`import '$_'` as $import where {
    register_diagnostic(
        span = $import,
        message = "Side Effect Import は禁止されています。",
        severity = "error"
    )
}

Refs

このスライドで Rust 系のツールも Plugin システムに対応しつつあることを知った

Plugin System in Rust based JavaScript / TypeScript Linters

TSKaigi 2025 Session 30 minutes biome: https://github.com/biomejs/biome deno_lint: https://github.com/denoland/deno oxc: https://github.com/oxc-pro&hellip;

speakerdeck.com

Footnotes

https://yaakai.to/blog/2025/cline-repository-refactoring/ でこのカスタムルールが書きたくて Biome → ESLint にした ↩

Dev Container で Chrome 拡張を Playwright でテストする

Tue, 17 Jun 2025 20:50:46 GMT

Playwright は Chrome 拡張もテスト出来るが、Dev Container で動かす際は CI と同様に install 時に --with-deps が必要。というだけの話ではあるのだが、地味にハマったのでメモに残す。

Chrome extensions

playwright.dev

$ npx playwright install --with-deps chromium

あとは公式にあるように channel: 'chromium' でテスト用のコンテキストを作ればよい。

context = await chromium.launchPersistentContext('', {
  channel: 'chromium',
  args: [
    `--disable-extensions-except=${pathToExtension}`,
    `--load-extension=${pathToExtension}`,
  ],
});

公式を読めば大体解決する話なのだが、 Cline 向けに Chromium を Dev Container に用意していた影響か、Claude Code が最初の動くものとして次のように設定してきて少しハマった。

context = await chromium.launchPersistentContext('', {
  headless: true,
  args: [
    `--disable-extensions-except=${pathToExtension}`,
    `--load-extension=${pathToExtension}`,
  ],
  executablePath: '/usr/bin/chromium'
});

これでも動作はするのだが(公式にも記載はある)、Chrome 拡張でないテストは playwright install chromium で入れたものを使うので Chromium が 2 つ必要になる。これをまとめる方法がよくわからなかったが channel を使うとこれを解決できる、公式をちゃんと読もう。

以下は最小構成のリポジトリ:

GitHub - yaakaito/playwright-chrome-extension

Contribute to yaakaito/playwright-chrome-extension development by creating an account on GitHub.

github.com

/command で Claude Code とのやり取りを Commit に残す

Mon, 09 Jun 2025 13:00:40 GMT

AI を使ってコードを書いているときに、そのやりとりを何かしらの形で残せると良いよねという課題感があったが、コミットメッセージに残せばよいというアイデアを見かけてこれを試している。

これを毎回そのようにしてと頼むのは面倒なので、 Claude Code の Slash Comannd として用意してそれを使っている。

Create a commit that includes **all conversation** between the user and yourself up to this point, following Conventional Commits format:

```
<type>[optional scope]: <description>

[optional body]

prompt: <user's input prompt>
----
<your response>
----
prompt: <user's input prompt>
----
<your response>

[optional footer(s)]
```

- Breaking changes: Use ! after type/scope or add BREAKING CHANGE: footer
- Common types: feat, fix, docs, style, refactor, test, chore, ci, build, perf
- Scope examples: (api), (ui), (auth), (parser)
- Description: Present tense, lowercase, under 50 chars, no period
- Separate conversation exchanges with ----

これを ~/.claude/commands/commit.md として保存しておくと /user:commit が使えるようになる。ルール化するなら project: にしてもいいと思う。

実際にできるメッセージは自分の入力はそのまま残る一方で、 Claude Code 側のものは結構要約されたりする。すべてそのまま残ってほしい気もするが、それはそれで膨大になりそうなので今のところ必要十分という感じ。

Refs

docs.anthropic.com

使ったプロンプトをコミットログにぶち込んでおくのCloudflareの人も実践してたhttps://t.co/Q0WSOsfPcW https://t.co/SKXx0Ytmwz
— Iaiso (@laiso) June 7, 2025

git worktree で Claude Code の並列稼働を試す

Sat, 24 May 2025 11:55:13 GMT

Claude Code Best Practices でも紹介されている方法で、 git worktree でコードベースを複製してそれぞれで Claude Code を実行する。自分は趣味の範囲は基本的に Dev Container でコーディングを行っているので、複数 clone してそれぞれでイメージを作って、とするのは面倒でこの方法を採用した。

Claude Code overview - Claude Code Docs

Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.

www.anthropic.com

Git - git-worktree Documentation

git-scm.com

ブランチ込みで作りたいときは、 -b でブランチを作成できる。

git worktree add ~/feature/foo-bar -b feature/foo-bar

Dev Container のマウント先は /workspace/[reponame] になっているはずで、ここから ../feature/foo-bar で /workspace/feature/foo-bar は作れないので ~ へ worktree を作っている。 worktree を作ると、そこに指定したブランチが co されているので、 cd して Claude Code で作業する。

$ cd ~/feature/foo-bar 
$ claude

最近は「Terminal: Create New Terminal in Editor Area」でエディターの領域でターミナルを開いてしまい、ファイルのタブと同じレベルでターミナルを管理して Claude Code を実行しているので、worktree 分このタブを増やせば良い。

作業が終わったら remove で削除する。

$ git worktree remove ~/feature/foo-bar

このブログを Remote MCP Server にして検索できるようにしてみる

Tue, 20 May 2025 00:00:00 GMT

技術的な素振りの側面が大きいが、比較的新し目のことを書いたりしているので MCP でブログの内容が検索できるとあとで実装に使いたいときに便利そうだと思ったので、このブログを Remote MCP Server にしてみた。

サンプルに毛が生えた程度の大したものではないが、コードはこのブログのリポジトリに含まれている:

yaakaito/mcp-server at main · yaakaito/yaakaito

Contribute to yaakaito/yaakaito development by creating an account on GitHub.

github.com

Cloudflare で Remote MCP Server を立てる

MCP といえばローカルで Node なんかで動いているイメージが強いが(もはやそうでもない？)、プロトコルとしては HTTP 経由でも利用できるようになっていて、先日 Cloudflare Workers でこれを動かす方法が公式から発表されたので、これに従っていく。

Build and deploy Remote Model Context Protocol (MCP) servers to Cloudflare

You can now build and deploy remote MCP servers to Cloudflare, and we handle the hard parts of building remote MCP servers for you. Unlike local MCP servers you may have previously used, remote MCP servers are Internet-accessible. People simply sign in and grant permissions to MCP clients using familiar authorization flows.

blog.cloudflare.com

Build a Remote MCP server

This guide will show you how to deploy your own remote MCP server on Cloudflare using Streamable HTTP transport, the current MCP specification standard. You have two options:

developers.cloudflare.com

少し前のテンプレートだと OAuth 認証がセットになっていて少しだるかった記憶があるが、最近試したら remote-mcp-authless というのになっていたので、ありがたくこれを使う。いつの間にかドキュメントが Bun のコマンドにも対応していた。

$ bun create cloudflare@latest my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless

ざっくり言えば Cloudflare の提供する agents/mcp で @modelcontextprotocol/sdk のサーバーをラップするとイメージで実装されている。それ以外は @modelcontextprotocol/sdk と同様に実装できるはずなので、それの詳しい説明は割愛する。

Cloudflare Agents

Build agents on Cloudflare—the platform designed for durable execution, serverless inference, and pricing that scales up (and down).

agents.cloudflare.com

GitHub - modelcontextprotocol/typescript-sdk: The official TypeScript SDK for Model Context Protocol servers and clients

The official TypeScript SDK for Model Context Protocol servers and clients - modelcontextprotocol/typescript-sdk

github.com

検索できる Tool を実装する

中身については、前に作ったこのブログの関連記事用の Vectorize を流用している。

Cloudflare Vectorize と Workers AI で関連する記事を作ってみる - yaakai.to

📚 Cloudflare Vectorize と Workers AI で関連する記事を作ってみる | yaakai.to

yaakai.to

Vectorize は Workers から使えるベクトルデータベースで、手軽にベクトルの保存や検索を行うことができる。

Cloudflare Vectorize

Vectorize is a globally distributed vector database that enables you to build full-stack, AI-powered applications with Cloudflare Workers. Vectorize makes querying embeddings — representations of values or objects like text, images, audio that are designed to be consumed by machine learning models and semantic search algorithms — faster, easier and more affordable.

developers.cloudflare.com

詳しい使い方や現状の実装は興味があれば前の記事を見てほしい、ここで作る MCP サーバーには、Vectroize からベクトル検索を行う Tool を実装しただけ。

// 記事を検索するツールを追加
this.server.tool(
    "yaakaito_search_articles",
    "キーワードや文章を入力して、関連する記事を検索します。",
    {
        query: z.string().describe("検索キーワードまたは文章"),
        limit: z.number().optional().describe("取得する記事の最大数（デフォルト: 3）")
    },
    async ({ query, limit = 3 }) => {
        try {
            const env = this.env as Env;

            // 検索クエリをベクトル化
            const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
                text: query,
            });
            const embedding = response.data[0];

            // 類似記事を検索
            const matches = await env.VECTORIZE.query(embedding, {
                topK: limit,
                returnValues: false,
                returnMetadata: true,
            });

            // 検索結果を整形
            const searchResults = matches.matches.map((match: any) => ({
                id: match.id,
                title: match.metadata?.title as string || "",
                content: match.metadata?.content as string || "",
                tags: (match.metadata?.tags as string[]) || [],
                path: match.metadata?.path as string || "",
                createdAt: match.metadata?.createdAt as string || "",
                updatedAt: match.metadata?.updatedAt as string || "",
                similarity: match.score
            }));

            return {
                content: [{
                    type: "text",
                    text: JSON.stringify(searchResults)
                }]
            };
        } catch (error) { }
    }
);

ベクトル化には引き続き @cf/baai/bge-base-en-v1.5 を使っているが、そこまで困っていない。 Tool を実装したらいつも通り Workers へデプロイし、今回は VSCode の Copilot に MCP Server を設定する。

// settings.json
{
  "mcp": {
    "servers": {
      "yaakaito": {
        "url": "https://{worker}.workers.dev/mcp" // or /sse
      }
    }
  },
}

もしくは MCP: Add Server... とかでもできると思う、適当に起動なり再起動をしたらツールが使えるようになるので適当に質問を投げてみる。

Resources としてブログ記事を追加する

MCP には Resources という機能もあり、Tool とはまた違う形で情報を提供することができる。

Resources - Model Context Protocol

modelcontextprotocol.io

今回の場合は、Resources に記事を配置しておくと、Claude Desktop でこんな感じに表示されて、プロンプトに本文を含めることができる。

Claude Desktop は Integrations が使えると URL のみでよいはずだが、Pro (以下) の場合は現状 mcp-remote を経由して設定する必要がある。

{
  "mcpServers": {
    "yaakaito": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://{url}.workers.dev/sse"
      ]
    }
  }
}

GitHub - geelen/mcp-remote

Contribute to geelen/mcp-remote development by creating an account on GitHub.

github.com

実装としては、デプロイ時に記事をコード化して Worker としてビルドしてしまうという方法にしている。

for (const article of articles) {
    this.server.resource(
        article.title,
        `articles://${article.id}.md`,
        { mimeType: 'text/plain', description: `${article.title} - ${article.content.substring(0, 50)}` },
        () => {
            return {
                contents: [{
                    uri: `article://${article.id}.md`,
                    mimeType: 'text/plain',
                    text: article.content,
                }]
            };
        }
    );
}

記事が増えるともう少し考えたほうがよさそうで、理想としては subscribe に対応するのがいいだろうが、そんな頻繁に増えるものでもないので、一旦はこれにしている。

デバッグ

開発をサポートするツールとして MCP Inspector と AI Playground が紹介されている。

GitHub - modelcontextprotocol/inspector: Visual testing tool for MCP servers

Visual testing tool for MCP servers. Contribute to modelcontextprotocol/inspector development by creating an account on GitHub.

github.com

Attention Required! | Cloudflare

playground.ai.cloudflare.com

自分は今回前者だけ使った、ただこれを Dev Container で動かそうとするとパッとはうまくいかなかったので、ホスト側で実行した。多分これと似たような問題でおそらく解決方法はあるが、面倒なのでやっていない。

Dev Container での wrangler dev で dev-server に繋がらない場合の対処 - yaakai.to

🖊 Dev Container での wrangler dev で dev-server に繋がらない場合の対処 | yaakai.to

yaakai.to

Claude Code を GitHub Actions で動かす

Sun, 20 Apr 2025 21:34:01 GMT

Claude Code は claude -p でユーザーとの対話なしに一度だけクエリを実行することができる。

Claude Code overview - Claude Code Docs

Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.

docs.anthropic.com

これを ANTHROPIC_API_KEY を設定した環境で実行することで CI として動作させることが可能になる(直近でこの部分にバグがあったが修正された)。

Claude Code overview - Claude Code Docs

Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.

docs.anthropic.com

Non-Interactive Mode Fails to Authenticate Using Provided API Key · Issue #551 · anthropics/claude-code

Environment Platform (select one): Anthropic API AWS Bedrock Google Vertex AI Other: Claude CLI version: 0.2.48 Operating System: Ubuntu (via Docker) Terminal: Docker container Bug Description In a...

github.com

以下は GitHub Actions で Issue にラベルをつけると解決を試みてくれるサンプル:

name: Claude Issue Solver

on:
    issues:
        types: [opened, edited, labeled]

permissions:
    contents: write
    issues: write
    pull-requests: write

jobs:
    analyze-issue:
        runs-on: ubuntu-latest
        # Only run when issues have the 'claude-solve' label
        if: contains(github.event.issue.labels.*.name, 'claude-solve')
        steps:
            - name: Checkout repository
              uses: actions/checkout@v3
              with:
                  token: ${{ secrets.GITHUB_TOKEN }}
                  fetch-depth: 0

            - name: Setup Git
              run: |
                  git config --global user.name "GitHub Action"
                  git config --global user.email "action@github.com"

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: 20.x

            - name: Setup PNPM
              uses: pnpm/action-setup@v3

            - name: Install dependencies
              run: pnpm install --frozen-lockfile

            - name: Install Claude Code
              run: npm install -g @anthropic-ai/claude-code

            - name: Create new branch
              run: |
                  BRANCH_NAME="claude-fix-issue-${{ github.event.issue.number }}"
                  git checkout -b "$BRANCH_NAME"

            - name: Save issue details
              env:
                  ISSUE_TITLE: ${{ github.event.issue.title }}
                  ISSUE_BODY: ${{ github.event.issue.body }}
                  ISSUE_NUMBER: ${{ github.event.issue.number }}
              run: |
                  # Save issue details to file for Claude to analyze
                  cat > issue.txt << EOF
                  Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}

                  ${ISSUE_BODY}
                  EOF
            - name: Evaluate issue solvability
              id: evaluate
              env:
                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
              run: |
                  export ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}
                  echo $ANTHROPIC_API_KEY
                  # Use Claude Code to evaluate if the issue can be solved
                  EVALUATION_JSON=$(cat issue.txt | claude -p "あなたはソフトウェアエンジニアとして、このIssueを解決できるかどうか評価してください。このIssueを解決するために十分な情報が含まれていれば「[Yes]」と返してください。そうでない場合は「[No]」と返して、その次の行に理由を述べてください。" --json)
                  echo "EVALUATION_JSON: $EVALUATION_JSON"
                  # Extract cost information
                  COST_USD=$(echo "$EVALUATION_JSON" | jq -r '.cost_usd')
                  echo "評価コスト: $COST_USD USD"

                  # Extract the result
                  EVALUATION=$(echo "$EVALUATION_JSON" | jq -r '.result')

                  # Extract yes/no response and reason
                  if echo "$EVALUATION" | grep -q "\[Yes\]"; then
                    echo "solvable=true" >> $GITHUB_OUTPUT
                    echo "reason=Issueには解決するための十分な情報が含まれています。" >> $GITHUB_OUTPUT
                  else
                    echo "solvable=false" >> $GITHUB_OUTPUT
                    REASON=$(echo "$EVALUATION" | sed -n '/\[No\]/,/^$/p' | tail -n +2)
                    echo "reason<<EOF" >> $GITHUB_OUTPUT
                    echo "$REASON" >> $GITHUB_OUTPUT
                    echo "EOF" >> $GITHUB_OUTPUT
                  fi

                  # Save total cost for reporting
                  echo "cost_usd=$COST_USD" >> $GITHUB_OUTPUT
            - name: Comment on unsolvable issue
              if: steps.evaluate.outputs.solvable != 'true'
              env:
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
                  ISSUE_NUMBER: ${{ github.event.issue.number }}
                  COST_USD: ${{ steps.evaluate.outputs.cost_usd }}
              run: |
                  COMMENT="## Claude 評価結果

                  このIssueは自動的に解決できません。

                  **理由:** ${{ steps.evaluate.outputs.reason }}

                  より詳細な情報を提供するか、要件を明確にしてください。

                  **コスト:** ${COST_USD} USD"

                  gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"

            - name: Solve issue
              if: steps.evaluate.outputs.solvable == 'true'
              id: solve
              env:
                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
              run: |
                  # Use Claude Code to solve the issue
                  SOLUTION_JSON=$(cat issue.txt | claude -p "このIssueを解決してください。リポジトリのコードを変更するために必要な作業を行ってください。" --json --allowedTools "Bash(git diff:*)" "Bash(git log:*)" Edit)

                  # Extract cost and result information
                  COST_USD=$(echo "$SOLUTION_JSON" | jq -r '.cost_usd')
                  RESULT=$(echo "$SOLUTION_JSON" | jq -r '.result')

                  echo "解決コスト: $COST_USD USD"
                  echo "解決結果: $RESULT"

                  # Save for reporting
                  echo "cost_usd=$COST_USD" >> $GITHUB_OUTPUT
                  echo "result<<EOF" >> $GITHUB_OUTPUT
                  echo "$RESULT" >> $GITHUB_OUTPUT
                  echo "EOF" >> $GITHUB_OUTPUT

            - name: Apply auto-fixes
              if: steps.evaluate.outputs.solvable == 'true'
              run: |
                  pnpm format || true
                  pnpm lint:fix || true
            - name: Create PR
              if: steps.evaluate.outputs.solvable == 'true'
              env:
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
                  ISSUE_NUMBER: ${{ github.event.issue.number }}
                  ISSUE_TITLE: ${{ github.event.issue.title }}
                  SOLVE_COST: ${{ steps.solve.outputs.cost_usd }}
                  EVAL_COST: ${{ steps.evaluate.outputs.cost_usd }}
                  SOLVE_RESULT: ${{ steps.solve.outputs.result }}
              run: |
                  BRANCH_NAME="claude-fix-issue-${ISSUE_NUMBER}"

                  # Calculate total cost
                  TOTAL_COST=$(echo "$EVAL_COST + $SOLVE_COST" | bc)
                  rm issue.txt
                  git add .
                  git commit -m "Fix: Issue #$ISSUE_NUMBER: $ISSUE_TITLE"
                  git push -u origin "$BRANCH_NAME"

                  PR_BODY="## Claude による自動修正

                  このPRはIssue #${ISSUE_NUMBER} を修正します。

                  **解決結果:**
                  ${SOLVE_RESULT}

                  **Claude AI コスト:** ${TOTAL_COST} USD

                  Claude AI 🤖 によって実装・テストされました"

                  gh pr create --title "Fix: ${ISSUE_TITLE}" --body "$PR_BODY" --base main

                  gh issue comment "$ISSUE_NUMBER" --body "修正用のPRを作成しました！ 🎉 確認をお願いします。Claude AIのコスト: ${TOTAL_COST} USD"

Claude Code で編集したあと eslint と prettier を実行して PR を作らせている、情報が不足していたら Issue にコメントが来るはずだが、いまのところかなり適当な内容でも解決しようとする。テストや eslint、prettier に失敗したらそれをもとに更に修正させることもしたかったが、yaml として書くのが面倒で今回はそこまではやっていない。

Roo Mode のような役割を与えるプロンプトを別途用意しておくと精度がよくなるかもしれない。

Workers AI の toMarkdown が便利

Sun, 20 Apr 2025 18:48:01 GMT

Markdown Conversion

Markdown is essential for text generation and large language models (LLMs) in training and inference because it can provide structured, semantic, human, and machine-readable input. Likewise, Markdown facilitates chunking and structuring input data for better retrieval and synthesis in the context of RAGs, and its simplicity and ease of parsing and rendering make it ideal for AI Agents.

developers.cloudflare.com

β 版な機能だが、いろんなものを Markdown に変換できて便利そう。今回自分は mozilla/readability で取り出した HTML を変換するのに使った。

const blob = new Blob([html], { type: 'text/html' });
const result = await this.env.AI.toMarkdown([
  {
    name: 'article.html',
    blob
  }
]);
const markdown = result[0].data;

実行には wrangler の ai フィールドの設定と、 --remote での起動が必要。LLM に食わせる用途なので、ローカルで動かすときは HTML をそのまま返すようにしている。

{
  "ai": {
    "binding": "AI"
  },
}

$ bun wrangler dev --remote

mozilla/readability はサンプルコードのままだと jsdom が Workers では動作しないので、そこは代わりに likendom を使った。

GitHub - mozilla/readability: A standalone version of the readability lib

A standalone version of the readability lib. Contribute to mozilla/readability development by creating an account on GitHub.

github.com

GitHub - WebReflection/linkedom: A triple-linked lists based DOM implementation.

A triple-linked lists based DOM implementation. Contribute to WebReflection/linkedom development by creating an account on GitHub.

github.com

Project Rules や .clinerules や CLAUDE.md をまとめて管理する

Mon, 24 Mar 2025 00:00:00 GMT

これを書いている 2025 年 3 月 24 日時点では、いわゆる rules ファイルを作って AI Coding の性能を向上させようという共通認識はあるものの、各種ツールでそのフォーマットは統一されていない。そのため現状では、複数のツールを使っていたり、人によってツールが異なるチームだと何かしらの方法でこれらを一元管理する必要があり、これは自分が今やっている方法を書き残したもの。

現状

Cursor / Project Rules

.cursorrules というファイルを使っていたが非推奨になり、 Project Rules という独自形式に移行した。

Cursor Docs

Cursor is the best way to build software with AI.

docs.cursor.com

ここで使われる .mdc 形式は Front Matter でルールを適用する範囲を glob で定義できる:

---
description: frontend の開発ルール（常に参照）
globs: packages/frontend/**/*
alwaysApply: true
---

性質が異なるので一元的に評価することは難しいが、Cursor の操作感と相まって他より 1 歩進んでいるという印象。

Cline / .clinerules

.clinerules というファイルを使っていたが、直近で .clinerules がディレクトリに出来るようになった。

docs.cline.bot

Cursor の mdc のように glob 機能があるわけではなく、単純に .clinerules ディレクトリにあるファイルがすべて適用される。コンテキストに含めるものの変更はファイルの移動が伴うため、公式に次のような運用が推奨されており、今回もこれを参考にしている:

clinerules-bank のような非アクティブなルールを格納しておくディレクトリを作る
複数人で運用する場合は .clinerules は gitignore に入れておき、各自が必要なものを移動させて利用する
コンテキストの切り替えをスムーズにするためのスクリプトを用意する

Roo Code

docs.roocode.com

Cline のフォークだが、少し特殊で .clinerules .cursorrules .windsurfrules の 3 つを読み込んでくれる。

Roo-Code/src/core/prompts/sections/custom-instructions.ts at main · RooCodeInc/Roo-Code

Roo Code gives you a whole dev team of AI agents in your code editor. - RooCodeInc/Roo-Code

github.com

Claude Code / CLAUDE.md

Not Found - Claude API Docs

Page not found

docs.anthropic.com

Cursor や Cline のディレクトリ化以前のシンプルなファイルと本質的には変わらないが、 claude を実行したディレクトリのものが適用されるという特性がある。当たり前といえばそうなのだが、これを Monorepo の場合で考えると、作業をする際にそのパッケージのディレクトリで claude を実行することでコンテキストを切り替えることができる。今回はこの特性を基準として rules の構成を考えている。

CLAUDE.md を Claude Code に作らせたときに面白かったことして、 claude code 自身の解説による /init がこのファイルは 20 行程度に作るべきだと定義しているっぽく、他のツールと比べて明らかに内容が少なくなる、というのがあった。自分はどちらかと言えばこれに賛成というか、(将来的には)長い知識を書き連ねるよりは、最小限にして毎度コンテキストを作ればいいよと思っている。

Copilot / .github/copilot-instructions.md

GitHub Copilot用のリポジトリカスタム命令の追加

docs.github.com

Cursor を使っていて、兼用はしていないので作っていない。

Windsurf / .windsurfrules

docs.codeium.com

これに関しては自分は Windsurf は使っていないのでそれに関する言及はないが、他とコンフリクトしないので Roo Code 用に作成している。

どう管理するか

現状を踏まえて次のようにやっている:

rules ディレクトリを作り、その中に Monorepo のパッケージ構造と同じになるようルールを分割して配置する
Cursor と claude はコンテキストに合わせたファイルをそれぞれ作成する
Cline と .windsurfrules はコンテキストを指定してファイルを配置したり結合する

前述した通り、現状では CLAUDE.md を Monorepo の各パッケージに配置することで実質的にコンテキストを切り替えることができる、というのを基準に考えている。コンテキストの切り替えを考える基準としては、ビジネス基準で考えるか技術基準で考えるかがあると思うが、 Monorepo 内で分けられたパッケージ単位でコンテキストが異なるレベルの技術が混在することは少ないだろうと考えて、ビジネス基準で分けている。 Single Repo (= リポジトリに一つのコンテキスト)の場合は単にファイルを分割して結合なりすればよいだけなので割愛するが、サブディレクトリが省略されるだけで同じものを使っている。

Monorepo の構造

自分が情報収集のために作っているアプリを例に出す。これはざっくりいうと以下の 4 つ(の種類)のパッケージがあり、それぞれでコンテキストを切り替えて開発したい。

RSS 収集し、 AI を使ってフィルタリングや要約を行うパッケージ
上で作られたデータや他の RSS を収集し、デイリーの単位でまとめを行うバックエンドアプリ
それを読むための Chrome 拡張
ユーティリティライブラリ

packages
├── claude-3
├── core
├── openai
├── reader-backend
├── reader-chrome-extension
├── rss-blog-release-notes
├── rss-books
├── rss-github-changelogs
├── rss-hatena-bookmark
├── rss-oss-release-notes
├── ...
├── rss-personal-blogs
├── rss-tech-blogs-en
├── rss-tech-blogs-jp
├── source-utils
├── string-utils
└── xml-utils

rules の構造

これに合わせて次のように rules を分割して配置している。

/
├── packages
└── rules
    ├── reader-backend
    │   ├── 01-init.md
    │   ├── 02-workflow.md
    │   └── 03-architecture.md
    ├── reader-chrome-extension
    │   ├── 01-init.md
    │   ├── 02-workflow.md
    │   ├── 03-architecture.md
    │   └── 06-patterns.md
    ├── rss-
    │   ├── 01-init.md
    │   ├── 02-workflow.md
    │   ├── 03-architecture.md
    │   └── 06-patterns.md
    ├── 01-init.md
    ├── 02-workflow.md
    ├── 03-architecture.md
    ├── 04-coding.md
    ├── 05-testing.md
    ├── 06-patterns.md
    └── generate-ai-rules.js

それぞれのファイルには名前に対応した内容を書いているが、 rules 直下のものにはより広い範囲の事柄を、それぞれのものには狭い範囲の事柄を書いている。例えば rules/03-architecture.md には Monorepo 全体の構造を書いて、 rules/reader-backend/03-architecture.md にはバックエンドアプリの設計方針が書いてある感じ。

工夫として、 01-init.md には次のように書いている:

最初に「reader-backend のコンテキストで処理しています。」と発言してください。

こうしておくことで、今読み込まれているものを認知できるようにしている。注意点として Cursor で 2 つのコンテキストをまたぐとうまく発言しないが、読み込み自体はうまく行っているはず。

また、ディレクトリ名が - で終わる場合は前方一致で対象のディレクトリを判定している。今回の場合は rss- で始まるパッケージには rss- 以下のルールがすべて適用される。

スクリプトで連結して配置する

rules/generate-ai-rules.js を実行するとそれぞれに対応するファイルが一括で出力されるようになっている:

$ ./rules/generate-ai-rules.js

このスクリプトは引数を取ることが出来て、 .clinerules と .windsurfrules はこの引数によって内容が変化する:

$ ./rules/generate-ai-rules.js reader-backend
$ ./rules/generate-ai-rules.js rss-

これを例えば reader-backend を引数に実行するとこのようにファイルが配置される:

├── .clinerules
│   ├── reader-backend
│   │   ├── 01-init.md
│   │   ├── 02-workflow.md
│   │   └── 03-architecture.md
│   ├── 01-init.md
│   ├── 02-workflow.md
│   ├── 03-architecture.md
│   ├── 04-coding.md
│   ├── 05-testing.md
│   └── 06-patterns.md
├── .cursor
│   └── rules
│       ├── reader-backend.mdc
│       ├── reader-chrome-extension.mdc
│       ├── rss-.mdc
│       └── rules.mdc
├── packages
│   ├── reader-backend
│   │   └── CLAUDE.md
│   ├── reader-chrome-extension
│   │   └── CLAUDE.md
│   ├── rss-blog-release-notes
│   │   └── CLAUDE.md
│   ├── rss-books
│   │   └── CLAUDE.md
│   ├── rss-github-changelogs
│   │   └── CLAUDE.md
│   ...
├── CLAUDE.md
└── .windsurfrules

あまり汎用的なスクリプトという感じでもないし、この状況が長く続くとは思えないので破棄のしやすさも兼ねて、それぞれのリポジトリに合うものを作っている。

わかりやすいものから順に内容を解説する。

.clinerules

Cline は rules 直下のものと、コマンドの引数で指定されたものを .clinerules ディレクトリに配置する。コンテキストを変えたいときは、スクリプトを実行して配置されているファイルを切り替える。

.windsurfrules

.clinerules と同じようにコマンドの引数でコンテキストが変わるが、ディレクトリには対応していないため 1 ファイルに内容をまとめる必要がある。例えば rss- パッケージの場合は次のような順でファイルを連結したものを .windsurfrules としている:

rules/01-init.md
rules/rss-/01-init.md
rules/02-workflow.md
rules/rss-/02-workflow.md
rules/03-architecture.md
rules/rss-/03-architecture.md
rules/04-coding.md
rules/05-testing.md
rules/06-patterns.md
rules/rss-/06-patterns.md

.cursor/rules

rules 直下のものはすべてを対象に、サブディレクトリ配下のものは対応するパッケージを対象に glob を設定して連結している。例えば rss- パッケージ向けのものはこのようになっている:

---
description: rss- パッケージのルール（常に参照）
globs: packages/rss-*/**/*
alwaysApply: true
---

最初に「rss- のコンテキストで処理しています。」と発言してください。

...

それぞれのファイルは次のように連結している:

.cursor/rules/rules.mdc
  - rules/01-init.md
  - rules/02-workflow.md
  - rules/03-architecture.md
  - rules/04-coding.md
  - rules/05-testing.md
  - rules/06-patterns.md
.cursor/rules/reader-backend.mdc
  - rules/reader-backend/01-init.md
  - rules/reader-backend/02-workflow.md
  - rules/reader-backend/03-architecture.md
.cursor/rules/reader-chrome-extension.mdc
  - rules/reader-chrome-extension/01-init.md
  - rules/reader-chrome-extension/02-workflow.md
  - rules/reader-chrome-extension/03-architecture.md
  - rules/reader-chrome-extension/06-patterns.md
.cursor/rules/rss-.mdc
  - rules/rss-/01-init.md
  - rules/rss-/02-workflow.md
  - rules/rss-/03-architecture.md
  - rules/rss-/06-patterns.md

これに似たアプローチは他の方も試されていてそちらも参考になる：

zenn.dev

CLAUDE.md

それぞれのパッケージに、 .windsurfrules として生成するものと同等のものを配置している。事前にすべて作っておけるイメージ。例えば packages/reader-backend/CLAUDE.md の内容は $ ./rules/generate-ai-rules.js reader-backend を実行したときに生成される .windsurfrules と同じものになる。

コンテキストの切り替えはディレクトリ移動して claude を実行することで行う:

$ cd packages/reader-backend
$ claude

その他

どのくらい効果があるかは分からないが、Claude Code の CLI モードでプロンプトを評価させている。

{
  "scripts": {
    "rules:lint": "rm -rf .cursor .clinerules CLAUDE.md .windsurfrules && claude -p \"あなたはリンターです。rules以下のmdファイルがあなたや他のAIコーディングツールに渡す情報として適切かをコードベースと照らし合わせてよく考えて回答してください。\""
  }
}

全くそうではないのに「このリポジトリは DDD でクリーンアーキテクチャです」みたいなことを書くとちゃんと怒ってくれるので、初期段階ではそれなりに効果があると思う。実行する前に関連ファイルを消しておかないと、連結済みのものを読んだ状態になるので注意。

Cline でリポジトリ構造の変更とアーキテクチャのルール整備をした

Wed, 19 Mar 2025 00:00:00 GMT

個人的に作っているアプリで Feature Sliced Design (FSD) というアーキテクチャを途中から採用していて、導入以前に書かれたコードはそれに沿っていないという状態のリポジトリがあり、今回これを Cline を使ってこの移行を完了させようと思った。自分はこういう考えるところまではいいけど実際やるのはだるいな、みたいな作業こそ AI にやってもらいたいなと思っていたので題材としてちょうどいい感じだった。

Feature-Sliced Design

Architectural design methodology for Frontend projects 🍰 - Feature-Sliced Design

github.com

zenn.dev

どんなアプリかというと Chrome のサイドパネルとタブで動く GitHub の Issue/PR/Discussion リーダーで、分かる方は Jasper の Chrome 拡張版とイメージしてもらえるといいと思う。完全に自分用に作っているのでコードの公開とかは出来ないので、うまいこと察してほしい。アプリがわからなくとも話自体は分かるようにしているつもり。

Jasper - A flexible and powerful issue reader for GitHub

You will be able to read, track and discover many active issues very flexibly by using Jasper in GitHub.

jasperapp.io

前提

Tier 4 の 3.7 Sonnet
このリポジトリでの AI Coding は Cursor で少しだけ
TypeScript で、Biome を Linter/Formatter として使っている(いた)
Cline だけでやりきる
Memory Bank は個人のカスタマイズとして利用している

やりたいと思っていたこと

このリポジトリを今後 AI と滞りなく開発できるよう状態にしたい。一旦 Cline だとして、そのためには次の要素が必要だと考えた:

リポジトリの構造の完遂
FSD に沿った ESLint のルール追加
既存コードへのテストの追加
.clinerules の整備

現状は、 AI 向けのルールやガードレールが一切存在していないので、それも同時に整備することを目標にする。

現状と目指す状態

今はこんな感じに FSD に沿って書いたものと、それ以前に大きく lib と app(side-panel) に分けて書いていたものが混在している:

src/
├── entities/ # FSD 導入後に書いたもの
│   ├── github-search-result/
│   │   ├── model/
│   │   └── ui/
│   └── timeline-item/
│       ├── model/
│       └── ui/
│
├── features/ # FSD 導入後に書いたもの
│   └── timeline/
│       └── model/
│
├── lib/ # FSD 導入以前のコードは大体ここにある
│   ├── github/
│   │   ├── gql/
│   │   │   └── fragment/
│   │   └── __fixtures__/
│   └── stream.ts          # 主要ロジック
│
├── shared/ # FSD
├── side-panel/ # この下に FSD 以前のアプリが作られている
│   ├── components/
│   │   ├── side-panel-content.tsx
│   │   ├── side-panel-header.tsx
│   │   └── side-panel.tsx
│   ├── hooks/
│   │   └── use-side-panel.ts
│   ├── model/
│   │   ├── side-panel-model.ts
│   │   └── types.ts
│   ├── store/
│   │   └── side-panel-store.ts
│   └── ui/
│       └── side-panel-ui.tsx
├── timeline/ # エントリーポイント類は FSD を反映していない
└── worker/

これをこんな感じに整理したい:

src/
├── app/
│   └── entries/
│       ├── side-panel/
│       │   ├── index.html
│       │   └── index.tsx
│       └── timeline/
│           ├── index.html
│           └── index.tsx
│
├── entities/
│   ├── github-search-result/
│   │   ├── api/
│   │   │   └── gql/
│   │   ├── model/
│   │   │   ├── converters.ts
│   │   │   ├── io.ts
│   │   │   ├── timeline-item.ts
│   │   │   └── type.ts
│   │   └── ui/
│   │       ├── detail.tsx
│   │       ├── icons/
│   │       └── timeline-item.tsx
│   ├── stream/
│   │   └── model/
│   │       ├── keys.ts
│   │       ├── query-helper.ts
│   │       └── type.ts
│   └── timeline/
│       └── model/
│           ├── io.ts
│           └── type.ts
│
├── features/
│   ├── stream-notifications/
│   │   ├── api/
│   │   │   └── gql/
│   │   └── model/
│   │       ├── events.ts
│   │       ├── notifications.ts
│   │       └── stream-management.ts
│   └── timeline/
│       └── model/
│           ├── update-timeline.ts
│           └── use-timeline.ts
│
├── pages/
│   ├── side-panel/
│   │   ├── model/
│   │   │   └── use-notification-item.ts
│   │   └── ui/
│   │       └── page.tsx
│   └── timeline/
│       └── ui/
│           └── page.tsx
│
├── shared/
│   ├── config/
│   │   └── types.ts
│   └── lib/
│       ├── browser/
│       ├── event/
│       ├── storage/
│       └── time/
│
└── worker/
    └── index.ts

基本的な作業の方針

適当な作業の単位を 1 ループとして、そのループを次のような手順で進めた:

Plan で実装、改修の方針を相談して決める
その計画を Markdown として保存しておく
Act で Markdown を計画として実行する
1. 必要な修正があれば適宜で修正をお願いする
2. コンテキストが足りなくなったり挙動が怪しくなったら、 Markdown を使って新しい Task に引き継ぐ
必要な修正が終わったら、その差分を Markdown に書き込ませてアップデート
update memory bank 、書き足すところがあれば .clinerules もアップデート
適切なメッセージで git commit

特徴として、 Plan の内容を逐一 Markdown として残しておく、というものがある。これはもっと小さい範囲で試してみて、あとにドキュメントとして残せるしよさそう、という感触があったのでこれを採用してみることにした。このファイルの作成ルールは .clinerules に書いている:

## ドキュメント規約

- `docs/plans/` - 計画ドキュメント
  - ファイル名は `{3桁の通し番号}_{kebab-case-name}.md` の形式で保存

これがある状態で、「計画を docs/plans に保存してから作業を始めてください」というような指示で ACT モードに切り替えると、その計画を保存してから進めてくれる。最終的には次の 17 個の計画で作業が終わった:

plans
├── 001_migrate-from-biome-to-eslint-prettier.md
├── 002_monorepo-removal-plan.md
├── 003_migrate-to-jest-and-react-testing-library.md
├── 004_feature-sliced-design-eslint-rules.md
├── 005_test-implementation-plan.md
├── 006_github-search-result-timeline-restructuring.md
├── 007_lib-to-fsd-refactoring.md
├── 008_timeline-to-fsd-refactoring.md
├── 009_side-panel-to-fsd-refactoring.md
├── 010_config-stream-type-refactoring.md
├── 011_update-stream-refactoring.md
├── 012_entities-to-features-reference-fix.md
├── 013_created-at-type-fix.md
├── 014_timeline-items-type-guard.md
├── 015_other-type-errors-fix.md
├── 016_side-panel-item-removal.md
└── 017_timeline-api-call-fix.md

後から思ったこととして、もっと細かく分けるべきだったのと、指定と時系列の把握が楽になるので連番を使いたいが、複数人の場合にはコンフリクトのリスクがある。作業をしていく中で、元々の計画とのズレが生まれたら Markdown にその差分を追記してもらっていた:

今回の実装に、計画との差分があれば @mdfile に追記を行ってください。

他に意識したこととして、常に .clinerules を更新することを組み込んでいた。これも作業が終わったあとに次のようなプロンプトで更新していた:

今回の作業内容で、 @.clinerules に記載すべきことがあれば追記してください。

これはある程度ワークしていたように思うが、これは絶対入れてほしいなというルールが生まれたときは、その旨を随時お願いしていた。

最後の git commit は、 .clinerules にフォーマットを書いて置くことで「commit して」というだけでいい感じにコミットメッセージを作ってくれるようにしていた:

### コミットメッセージ規約
```
<type>(<scope>): <適切なメッセージ>

- <詳細な変更内容>
- <詳細な変更内容>
```

実際の作業で特筆すべきところ

大きめのポイントや詰まったところ、その解決を抜粋して書く。それぞれを細かく解説しているわけではない。

ESLint のルール作成関連

001_migrate-from-biome-to-eslint-prettier

Biome から ESLint と Prettier に移行した、理由としてはカスタムルールが作りやすそうだったから。モジュール関連の地雷を多少踏みながらも滞りなく移行できて、さすがこういうのは得意という感じだった。

004_feature-sliced-design-eslint-rules

その後、FSD に沿ったアーキテクチャになるよう ESLint のルールを Cline に作ってもらった。 FSD のドキュメントやそこから抜粋した内容を渡して少し長めの Prompt から始めた。

このリポジトリは Feature Sliced Design (FSD) の考え方を取り込んだ構造になっており、現在は既存のコードをそれに向けて移行している最中です。FSD については @https://feature-sliced.design/docs や @https://feature-sliced.design/docs/get-started/overview を参照してください。
移行作業を進める前に、 ESLint でコードの配置に関するルールを作成します。
次のルールを作成してください:

- Layers は上から下にしか参照できないルール
- Layers 配下には Slices が配置され、さらにその配下に Segments が配置され、適切なコードが置かれるルール

ただし、現在コードを移行中のため、ルールに該当しないディレクトリにあるコードはすべて無視してください。

## Layers は上から下にしか参照できないルール

コードは次のいずれかのレイヤーに配置されます:

- app* — everything that makes the app run — routing, entrypoints, global styles, providers.
- pages — full pages or large parts of a page in nested routing.
- features — reused implementations of entire product features, i.e. actions that bring business value to the user.
- entities — business entities that the project works with, like user or product.
- shared* — reusable functionality, especially when it's detached from the specifics of the project/business, though not necessarily.

これは FSD の考え方から widgets と processes を省略したものです。
レイヤー間の参照は上から下にしか行うことが出来ず、例えば pages から features のモジュールを import することは出来ますが、その逆は出来ません。同じレイヤーでの横の参照は許可されます。
このルールが守られていることを ESLint でチェックできるようにしてください。

## Layers 配下には Slices が配置され、さらにその配下に Segments が配置され、適切なコードが置かれるルール

FSD では pages, features, entities レイヤーの下に Slice が配置され、さらにその配下に Segment が配置されます。
コードは任意の場所に配置出来ないため、このルールを守ることを ESLint でチェックできるようにしてください。

公式から引用したルールは次のようになります:
Slices
Next up are slices, which partition the code by business domain. You're free to choose any names for them, and create as many as you wish. Slices make your codebase easier to navigate by keeping logically related modules close together.

Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling.

Segments
Slices, as well as layers App and Shared, consist of segments, and segments group your code by its purpose. Segment names are not constrained by the standard, but there are several conventional names for the most common purposes:

ui — everything related to UI display: UI components, date formatters, styles, etc.
api — backend interactions: request functions, data types, mappers, etc.
model — the data model: schemas, interfaces, stores, and business logic.
lib — library code that other modules on this slice need.
config — configuration files and feature flags.
Usually these segments are enough for most layers, you would only create your own segments in Shared or App, but this is not a rule.

Cline と相談して、最終的に 5 つのルールを作ることになった:

# Feature Sliced Design (FSD) に基づいたESLintルールの実装

Feature Sliced Design (FSD) アーキテクチャに基づいたESLintルールを実装しました。これにより、コードベースがFSDの原則に従っているかを自動的にチェックできるようになります。

## 実装したルール

###レイヤー間の参照ルール

- 上位レイヤーから下位レイヤーへの参照のみ許可
- app → pages → features → entities → shared の順で参照可能

### 同一レイヤー内のSlice間参照禁止

- 例：entities/userからentities/productへの参照は禁止

### レイヤー構造ルール

- appとsharedレイヤーは直接Segmentsを配置
- pages, features, entitiesレイヤーはSlices配下にSegmentsを配置

### Public API強制ルール

- Sliceの内部実装を直接参照せず、公開APIのみを通じて参照
- 例：import { Something } from '@src/entities/user'は許可
- 例：import { Something } from '@src/entities/user/model/something'は禁止

### バレルファイル内容検証ルール

- index.tsファイルはimportとexportのみを含むべき
- ロジックや実装詳細は含めない

注意点として、ESLint を作ろうとするときに広く使われている TIPS を取り込んだり、 ESLint のプラグインだと認識しているからかやたら汎用的なコードを書きたがる傾向があるように思う。前者としては、 @src のようないわゆる paths をこのリポジトリでは採用していなかったが、それが採用されているかのようなコードを書いていた。

後者は、例えば設定を eslint.config.js で出来るようなコードを書こうとして、結果複雑になる上に動作しないような状態になっていた。これは「設定ファイルで出来る必要はないし、シンプルにベタ書きで実装すればいいよ」というような指示をしてあげると、考えることが減るのかちゃんと動くコードが出てくる

そんなこんなで ESLint を実行するとルールが適用され、 Cline が自身の書いたコードの誤りを検出できるようになった:

/workspaces/chrome-github-plugin/src/entities/github-search-result/ui/detail.tsx
  1:1  error  Sliceの内部実装を直接参照せず、公開API(features/timeline)を通じて参照してください。各Sliceはindex.tsでのみ外部に公開されるべきです。               fsd/public-api
  1:1  error  レイヤー 'entities' から上位レイヤー 'features' への参照は禁止されています。レイヤーは上から下にのみ参照可能です。                                fsd/layer-imports
  2:1  error  同一レイヤー 'entities' 内の異なるスライス間の参照は禁止されています。スライス 'github-search-result' から 'timeline-item' への参照はできません。  fsd/slice-imports

テストを作ってもらう

003_migrate-to-jest-and-react-testing-library

テストが全く無かったわけではなく、動作確認程度に Node の組み込みランナーでテストは書いていたが、 AI が書いてくれるなら React もやるかということで Jest と React Testing Library へ移行してもらった。例によってモジュール関連でゴチャることがあるものの、概ね得意。

005_test-implementation-plan

全部のコードのテストを書いてもらう計画を立てた。とはいえ、元々テストを書くことを考えて書いていないコードなので、コードを変更しないと書けないのであれば無視してよい、というルールにした:

src 以下のテストが書かれていないコードに対して単体テストを追加します。
また、node:test から Jest への移行が出来ていないテストがあれば、それを Jest へ移行してください。
元のコードを変更することはせず、テストのためにコードを変更することは避けてください。
テストを書くことが難しければ、無視して構いません。

が、実際には「細かく分けたらテストできそうなので分けました！」と分けてくることがありつらい。

テストの内容を書いてもしょうもないのでそれは割愛する。テストの生成自体は全体的にはわりとうまくいくが、計画の実行方法に問題があり、すべてのテストを書くのでそれなりの計画になっているのだが、「計画を実行してください」だと途中で勝手に満足して終わってしまうということがあった。「いくつかのファイルに対してテストを追加・移行することができました。」ではなく全部やってほしい:

# テスト追加・移行完了レポート
テスト追加・移行計画に基づいて作業を進め、いくつかのファイルに対してテストを追加・移行することができました。

ここでは解決策として「すべてのステップが終わるまで続けて」とどの程度やってほしいのかを明確に伝えることでワークしたのだが、あとで思ったこととしてもっとタスクを分割するべきだった、というのがある。これは辻褄合わせフェーズではこの形を取ることにした。

コードの移動や分割

これ全般に言えることとして、テスト、Lint、型チェックを仮でもよいので全て通してからこの作業に入るべきだった、という反省がある。

過去の経験から、多少テストや Lint が落ちている状態でも、その Task に関係がないものはうまく無視出来ている事が多く、今回もそれがうまく働いて最後に辻褄を合わせればよいだろう、と考えていた。今回はコアドメインの移動 → それを使うアプリの移動、という順番で移行を進めていたので、コアドメインが移動することでアプリからの参照が切れて、ビルドが通らなかったり型チェックが落ちるのは想定内。だがそれを「今回とは関係ないエラー」と認識していることがかなり多く、これはなるべく修正しながら進んでほしかった。

結果としては最後の辻褄合わせで大した苦労はなく、移行としては成功しているのだが、途中でほとんどビルドが出来なかったりといったところでそれなりに不便があった。とはいえ最後にちゃんと合うなら全体としてみればよかったとも言えるので、少しむずかしいところだなと思う。まぁこのあたりは人間がやる場合でも変わらないのでは？と言われればそうなのだが。

002_monorepo-removal-plan

このリポジトリは元々 Monorepo になっていたのだが、このタイミングでルートへ統合した。大量にファイルを移動するを AI にやらせるは無駄だという肌感があったので、移動はこちらでやるということを明示して計画を立ててもらった。

007_lib-to-fsd-refactoring

今回の肝で、適当に書いていたコードを FSD に沿って分割しながら再配置した。ぱっとイメージがあったわけではないので、分析して計画を大まかに立ててもらうところから始めた。

@/src/lib/ 以下のコードを FSD のルールにそって適切な構成に作り変えます。
まずは大まかにプランを考えてください。

いろいろ相談していったのだが要点としては以下:

似たような概念が FSD と lib それぞれに存在していて、これらを別々のものとして扱おうとしていたので、統合してもらうようにした
アプリのドメイン知識が足りずに Notification を一般的な通知機能だと思い込み独立させようとしていた、これはこのアプリでは少し違う概念なので軌道修正した
- これはアプリ内では「更新があったIssue」くらいの意味で使われていた
GraphQL の query の扱い方を相談して決めた

計画が出来たら、細かいステップに分割してとお願いした後に、適当な単位で git commit するようにお願いしていた(これは .clinerules に含める以前の話):

計画の詳細さは維持したまま小さいステップに分割して

各ステップで git commit を行うようにしてください、フォーマットは以下

git add .
git commit -am "refactor: <適切なメッセージ>

- 詳細
- 詳細
- 詳細
"

で、これがうまく行ったかというと前述した通りあまりうまくいかなくて、途中まで進めて満足したのか止まってしまう。ステップごとの git commit も途中まではうまく行っていたのだけど、一度止まったあとに再開させるとその指示が Markdown に含まれているのにもかかわらず忘れてしまったりで、ぐぬぬという感じだった。今回は Cline 自体の検証も兼ねているので、満足行くような動きをするまでこのフェーズを何度かやり直していて、実装フェーズの実行だけで合計 $30 くらい吹き飛んでいった。つらい。

結果としてはここは「チェックリストを別ファイルとして作ってアップデートしながらやって」というのがある程度ワークしていてやり切ることは出来たのだが、更新のタイミングがまちまちだったりしてあまりおすすめできる感じではなかった。ちゃんと更新のルールをつめてあげるとか、Roo Code であればそういう Mode を作ればうまくいきそうという感じはしたが、あまりおすすめできない感じ。こんなプロンプトでやっていた:

@/docs/plans/007_lib-to-fsd-refactoring.md に沿って、 src/lib 以下を FSD に準じたコードにする作業を進めます。
最初に docs/checklist.md として詳細な作業のチェックリストを作ってください。ステップ毎の作業は以下の手順で進めるようにしてください。

```
1.  pnpm test を実行し、前の作業が問題を残していないことを確認する
2. 各ステップの実装を行う
3. 単体テスト: `pnpm test -- <作業したディレクトリ>`
4. 型チェック: `pnpm tsc --noEmit`
5. リンティング: `pnpm lint <作業したディレクトリ>`
6. 関連テスト: 作業内容に影響を受ける可能性のある他のテストを実行
7. 以下の形式で変更をすべて git commit

refactor: <適切なメッセージ>

- 詳細な変更点
- 詳細な変更点
- 詳細な変更点
```

以後何か作業を進めるごとに必ずこのチェックリストを更新しながら進めます。
準備が出来たら、すべてのステップの作業が完了するまで作業を続けてください。

一方でモデルの統合は計画で時間を書けたからかうまくやってくれていた、えらい。あとはテストを移行するのを忘れるので、ちゃんと指示に含めたほうがよさそうだった。

辻褄合わせフェーズ

010 以降がこれにあたり、前述通り計画が大きすぎた反省を活かして、 Plan としては「pnpm eslint を実行して全部直して」くらいのものから始めるが、計画を保存するときに具体的な内容で分割して保存するようにした:

deleteLogic と ConfigStream へのリネームに関する作業計画と、 updateStreamの呼び出しに関する作業計画をそれぞれ docs/plans に書き出してください

こうすると 010 と 011 に計画を分けてくれたので、小さくなった個別の Task をそれぞれ実行させて完了させていった。番号のつけ方はともかく、これは結構うまく行ったように思う。

.clinerules

終盤になって .clinerules にある程度情報が溜まった来たところで .clinerules をブラッシュアップさせた:

@/.clinerules をよりよいものにアップデートしたいと考えています。
より良いとは、次のような基準です。

- 明確かつ簡潔であること
- 全体のトーンが揃っていること
- 重要なアーキテクチャの核心についてはより詳しく書かれていること
- 特殊な表記を使わず、見出し、段落、箇条書き、リストを中心とした、人にも読みやすいシンプルな構成
- 記載されている順序がよく練られており、上から順に読めば開発に着手できる

また、次のような要素を付け加えたいと考えています。

- 簡単なコードを書くこと
- 早期リターンを意識しフラットな構造にする
- 関数で書くことを優先する
- ...

よりよい .clinerules が作れるよう、コードベースも参考にして考えてください。

最終的には次のような内容になった:

# プロジェクトルール

## 重要

1. コード変更前にテストを確認し、実行する
2. テストで期待する動作を事前に定義する
3. コード作成後、テストと静的解析を実行
4. 3回連続で問題解決できない場合、ユーザーに相談する

## 開発ワークフロー

### コマンド一覧
- **開発サーバー起動**: `pnpm dev`
- **ビルド**: `pnpm build`
- **テスト実行**: `pnpm test`
  - 特定のテストファイル実行: `pnpm test -- <filename>`
- **テスト（監視モード）**: `pnpm test:watch`
- **テストカバレッジ**: `pnpm test:coverage`
- **リンティング**: `pnpm lint`
  - 特定ファイルのリント: `pnpm lint -- <filename>`
- **コード自動修正**: `pnpm lint:fix`
- **フォーマット**: `pnpm format`

### 開発フロー
1. **機能実装前**: テストを先に書く（TDD）
2. **コード変更時**: 既存テストが通ることを確認
3. **コード作成後**: テストを実行して期待通りの動作を確認
   ```bash
   pnpm test -- <filename>  # 特定のファイルのテストを実行
   # または
   pnpm test                # すべてのテストを実行
   ```
4. **テスト失敗時**: テストが通るようにコードを修正
5. **リファクタリング時**: テストが引き続き通ることを確認
6. **コミット前**: ESLintを実行してコードスタイルを確認
   ```bash
   pnpm lint
   pnpm lint:fix  # 自動修正可能な問題を修正
   ```

### 拡張機能のロード方法
1. Chromeで`chrome://extensions`を開く
2. デベロッパーモードを有効化
3. `packages/extention/dist`ディレクトリを読み込む

### コミットメッセージ規約
```
<type>(<scope>): <適切なメッセージ>

- <詳細な変更内容>
- <詳細な変更内容>
```

## 開発の基本原則

### コード品質
- **シンプルなコード**: 複雑な実装より読みやすいコードを優先
- **早期リターン**: 条件分岐はネストを避け、早期リターンでフラットな構造に
  ```typescript
  // 良い例
  function processItem(item) {
    if (!item) return null;
    if (item.isInvalid) return null;

    return transformItem(item);
  }

  // 避けるべき例
  function processItem(item) {
    if (item) {
      if (!item.isInvalid) {
        return transformItem(item);
      }
    }
    return null;
  }
  ```

### 関数型アプローチ
- **関数優先**: クラスよりも関数で実装
- **純粋関数**: 副作用を持たない関数を優先
- **ループ処理**: `forEach`を避け、`for...of`または配列メソッドを使用
  ```typescript
  // 良い例（非同期処理の場合）
  for (const item of items) {
    await processItem(item);
  }

  // 良い例（同期処理の場合）
  const results = items.map(item => processItem(item));

  // 避けるべき例
  items.forEach(async (item) => {
    await processItem(item); // 非同期処理の制御が難しい
  });
  ```

### 依存管理
- **依存の最小化**: 可能な限りリポジトリ内のコードで解決
- **依存追加時**: 必ずユーザーに確認
- **外部依存のモック**: テスト時に外部依存を適切にモック化

### 抽象化
- **過度な抽象化を避ける**: 具体的で理解しやすいコードを優先
- **Sliceの具体性**: 抽象的なコードよりも具体的な実装を優先

## アーキテクチャ（Feature Sliced Design）

### レイヤー構造
1. **app** — アプリケーション実行に必要な要素
   - エントリーポイント、グローバルスタイル、ルーティング
2. **pages** — 完全なページまたはネストされたページ部分
3. **features** — ユーザーにビジネス価値をもたらす機能
4. **entities** — ビジネスエンティティ（GitHub Search Result、Timeline Itemなど）
5. **shared** — 再利用可能な機能（プロジェクト/ビジネスから独立）

### 参照ルール
- 上位レイヤーから下位レイヤーへの参照のみ許可
  - `app` → `pages` → `features` → `entities` → `shared`
- 下位レイヤーから上位レイヤーへの参照は禁止
- 同一レイヤー内のSlice間の参照も禁止

### Slice構造
- **app**と**shared**レイヤーは直接Segmentsを配置
- **pages**, **features**, **entities**レイヤーはSlices配下にSegmentsを配置

### Segment構造
- **ui** — UI表示（コンポーネント、スタイルなど）
- **model** — データモデル（スキーマ、ロジックなど）
- **api** — バックエンド連携（リクエスト関数など）
- **lib** — 他のモジュールが必要とするライブラリコード
- **config** — 設定ファイルとフラグ

### Public API
- 各Sliceの公開APIはindex.tsで明示的にエクスポート
- Sliceの内部実装詳細を直接参照することは禁止
- 各sliceの直下には必ずindex.tsファイルを配置

```typescript
// entities/github-search-result/index.ts
export * from './api';
export * from './model/io';
export * from './model/timeline-item';
export * from './model/type';
export * from './ui/detail';
// ...
```

## コーディング規約

### TypeScript
- 型定義を厳格に行う
- 型ガード関数を活用して型安全性を確保
  ```typescript
  function isCommentTimelineItem(item: any): item is CommentTimelineItem {
    return item.type === 'IssueComment' && 'bodyText' in item;
  }
  ```

### Reactコンポーネント
- 関数コンポーネントとして実装
- Reactフックを活用
- プロパティベースの設計（下位レイヤーのコンポーネントは上位レイヤーの機能を直接参照しない）

### スタイリング
- CSSモジュールを使用してスタイルをコンポーネントスコープに保つ
  ```typescript
  import styles from './component.module.css';

  function Component() {
    return <div className={styles.container}>...</div>;
  }
  ```

### ファイル命名
- ファイル名はキャメルケースを使用
- テストファイルは`.spec.ts(x)`という命名規則

### インポート
- 相対パスのみ使用（エイリアスは使用しない）
- パス記法は`./{path}`、`../{path}`のみ
  ```typescript
  // 良い例
  import { Button } from '../../shared/ui/button';

  // 避けるべき例
  import { Button } from '@shared/ui/button';
  ```

## 実装パターン

### ストリーム更新パターン
- `updateStream`関数でGitHubからデータを取得
- 各ストリームは`onUpdateThisLoop`関数で更新タイミングを制御
- 更新後は`notifyUpdated`でイベントを発行

```typescript
export const updateStream = async (name: keyof typeof streams, storage: Storage) => {
  // データ取得ロジック
  // ...

  // 通知条件の判定
  if (item.type === 'Issue' && shouldNotifyIssue(item, 'username', lastUpdated)) {
    createNotificationIfNeeds(storage, item.id, lastUpdated);
  }

  // ストレージ更新
  await Promise.all([
    setToStorage(storage, keyForItem(item.id), item),
    setToStorage(storage, keyForStreamItems(stream), newIds),
  ]);

  // イベント発行
  notifyUpdated(name, updatedIds);
};
```

### ストレージ管理パターン
- キーは`keyFor*`関数で生成（一貫性のため）
- `getFromStorageOrDefault`と`setToStorage`を使用
- アイテムIDをリストとして保存し、実際のデータは個別に保存

```typescript
const ids = await getFromStorageOrDefault(storage, keyForStreamItems(stream), () => []);
const items = [];

for (const id of ids) {
  const item = await getFromStorageOrDefault(storage, keyForItem(id), () => null);
  if (item) {
    items.push(item);
  }
}
```

### 通知システム
- `shouldNotifyIssue`と`shouldNotifyDiscussion`で通知条件を判定
- `createNotificationIfNeeds`で通知を作成
- `notifyNotificationUpdated`でイベントを発行

### イベント処理
- カスタムイベント（`stream:updated`、`notification:updated`）を使用
- `subscribeStreamUpdated`と`subscribeNotificationUpdated`で購読

```typescript
// イベント発行
export const notifyUpdated = (name: string, ids: string[], worker = false) => {
  dispatchUpdate('stream:updated', { name, ids }, worker);
};

// イベント購読
useEffect(() => {
  const unsubscribe = subscribeStreamUpdated(({ name }) => {
    if (name === streamName) {
      fetchData();
    }
  });

  return () => unsubscribe();
}, [streamName, fetchData]);
```

### プロパティベースのコンポーネント設計
- FSDレイヤー間参照ルールに従うため、下位レイヤー（entities）のコンポーネントは上位レイヤー（features）の機能を直接参照しない
- 通知状態などの機能は上位レイヤーからプロパティとして注入する
- 例: `IssueLine`コンポーネントは`hasNotification`や`onDeleteNotification`をプロパティとして受け取る

### 非同期処理パターン
- async/awaitを使用した読みやすい非同期コード
- Promise.allを使用した並列処理
- for...ofループを使用した非同期処理（forEachではなく）

```typescript
// 並列処理
const results = await Promise.all(
  queries.map(query => fetchData(query))
);

// 順次処理
for (const item of items) {
  await processItem(item);
}
```

## テスト戦略

### テストファイルの配置
- 実装ファイルと同じディレクトリに配置
- `.spec.ts(x)`という命名規則を使用

### テストファースト
- テストを先に書くことで、仕様を明確にする
- 実装前にテストを書くことで、APIや動作の設計が洗練される
- テストが通るように実装することで、要件を満たす保証になる

### テスティングトロフィー
- テスティングトロフィーを意識し、過度なモック化は避ける
- 単体テスト、統合テスト、E2Eテストのバランスを考慮
- 実際のユーザー体験に近いテストを優先
- モックは必要最小限にとどめ、可能な限り実際の実装を使用

### テスト関数
- `test`関数を使用（`describe`や`it`は使用しない）
- 日本語でテスト内容を記述

```typescript
test('初期状態ではpendingがtrueで、データ取得後にfalseになる', async () => {
  // テスト実装
});
```

### モックの活用
- Jestのモック機能を使用
- 外部依存関係を適切にモック化
- 過度なモック化は避け、実際の動作を反映したテストを心がける

```typescript
jest.mock('../../../entities/timeline/model/io');
jest.mock('../../../shared/lib/event');

beforeEach(() => {
  (timelineIO.getTimeline as jest.Mock).mockResolvedValue(mockTimeline);
});
```

### UIコンポーネントテスト
- React Testing Libraryを使用
- レンダリングの検証
- ユーザーイベントのシミュレーション
- アクセシビリティを考慮したセレクタの使用

```typescript
test('「Show all events」ボタンをクリックするとすべてのイベントが表示される', () => {
  render(<TimelineItems items={items} />);

  // ボタンをクリック
  fireEvent.click(screen.getByText(/Show all events/));

  // 表示を検証
  expect(screen.getByText(/testUser commented/)).toBeInTheDocument();
});
```

## コメント規約

- `TODO`: 将来的に実装すべき機能
- `MEMO`: 実装の背景や理由の説明

## ドキュメント規約

- `docs/plans/` - 計画ドキュメント
  - ファイル名は `{3桁の通し番号}_{kebab-case-name}.md` の形式で保存

## 制約と注意点

### GitHub API制限
- レート制限に注意（短時間に多数のリクエストを送らない）
- エラーハンドリングを適切に実装

### サービスワーカー制約
- サービスワーカーのライフサイクルに注意（長時間実行できない）
- 定期的なウェイクアップと処理の分散

### 既知の問題
- ユーザー名がハードコードされている箇所がある（将来的に設定から取得するよう変更予定）
- 初回データ取得時の挙動に制限あり

ちなみにこれを書いている途中に .clinerules がディレクトリにできるようになった。

所感

計画の管理方法と区切り方

管理方法に関しては答えがあまり考えられていないのだけど、計画の Markdown を中心に回すのは自分としては好みのフローだった。フロー以外にも、想定していないとか動作がおかしなコードが見つかったときに、それがどこで生まれたかを Markdown を遡って探しに行ってくれていたりして、そういう意味もあったほうがいいのだとは思う。とはいえ、ちょっとした bugfix まですべて管理したいのかと言われるとそうでもなく、 PR の単位で一つあればいいような温度感なので、 Plan というよりは Design Doc のような感覚で残せるといいのかなと思う。

番号は指定が楽になるので割とほしくて、複数人で管理する場合はやはり GitHub Issue などに連携できるとよさそう。そうするとそれをフロー化した Roo Code のカスタムモードが使いたくなるな、という感じだった。

実際の管理方法をどのようにしていくかにもよるが、計画自体は思っている 3 倍くらいは細かくしたほうがいいなと思った。 Design Doc のような形にする場合は、あまり分かれすぎていても効果が薄そうなので、 Git 管理下にない場所で個人的に使うのも手かもしれない。

Lint は AI に整備させる

結構ちゃんとしたものがすぐに出てくるので便利。汎用的なものを作ろうとする傾向にあるように思うので、局所最適して良いことを伝えると精度が上がるように思う。

多分作り直させたほうがいい

既存のコードを大きく書き換えるよりも、既存のコードを解析させて仕様抽出、その仕様をもとに新しいコードを生成させる方が得意だろうと思うので、今回のように Cline で移動させるみたいなのはあんまり向いていない気もする。途中でやり直しているフェーズがいくつかあるとはいえ、やり切るのに大体 $100 かかっていて、「これ作り直したほうが安くね？」と思いながらやっていた。

名前を横着せずにちゃんとつける

別に人間がコードを書く場合でも変わらない話ではあるが、抽象度が高い名前を使っていると勝手に役割を推測されているような感覚があった。新しく作る場合よりは、既存のコードを解析させたりリファクタリングさせる場合にこれは大きく影響してきそう、という肌感。

2025年3月時点での Memory Bank と .clinerules の使い分けに関する考え

Thu, 13 Mar 2025 00:00:00 GMT

Cline (Roo Code) を使っているとよく出てくる概念として Memory Bank というものがある。

docs.cline.bot

これのコンセプトはなんとなく理解できるものの、「じゃあ .clinerules との使い分けはどうなんだ」「Memory Bank は commit するべきなのか？」というのがあまり分かっていなくて、そこにフォーカスして考えた内容。

これを書いている 2025 年 3 月初旬時点の頭の中をダンプした個人的な記録で、完全に間違っているかもしれないし 1 週間後にはまったく違うことを言っているかもしれない、というものなのでご了承いただきたい。また、基本的にはコードを複数人で触ることを前提として考えている。

ここでは特に Cline の Memory Bank について書いて、基本的なコンセプトなどは分かっているものだとする。解説がほしい方は以下の記事がおすすめ。

zenn.dev

Roo Code 向けの Memory Bank として以下のものがあることは知っているが、使ったことはない。

GitHub - GreatScottyMac/roo-code-memory-bank: 🧠 Roo Code Memory Bank: Seamless project context in Roo Code. No more repetition, just continuous development!

🧠 Roo Code Memory Bank: Seamless project context in Roo Code. No more repetition, just continuous development! - GreatScottyMac/roo-code-memory-bank

github.com

現時点での使い分け

「.clinerules をリポジトリに含めて育て、 Memory Bank は個人をサポートするツールとして利用する」に自分の中で落ち着いた。

.clinerules

これに記載するべき内容については散々各所で言われていると思うので割愛する。 Git などの管理下において共有し、これがあれば Cline での開発を進めることができるだろう、という状態を目指したい。基本的には人間が記述し管理する、もしくは AI が生成したものを人間が編集しレビューする、という形で運用する。

Memory Bank

Memory Bank は個人のカスタムプロンプトとして利用して、その成果物を共有しない。個人がどのように使うか、そもそも使うか使わないかも管理しないことにする。生成されたドキュメントをどこで管理するかというの問題があるが、個人で gitignore してもらうか、配置場所のルールを決めてそこを gitignore しておく。

なんでそう思ったか

Memory Bank は出力が安定しているわけではない

これは自分の設定や使い方の問題の可能性があるが、Memory Bank の出力する md ファイルは毎回同じ内容が安定して手に入るわけではない、という認識をしている。ある意味当たり前の話ではあるのだが、ある程度コードのあるリポジトリで何度か作り直したりすると、毎回違うものが出てくる。違うといっても主にフォーマットや言葉遣いの話で主要なところはだいたい似通っているのだけど、なんにせよこれを共有したいかというとそういう気にはならなかった。うまくプロンプトを書けば安定が手に入る…のかもしれない。

activeContext や progress は完全に個人の作業状況に依存する

という認識をしている。共有したいものではないし、これを共有するよりは Plan や Architect の出力をリポジトリに含める方が、他の人があとから参照させることもできたりして効果が高そう。

Memory Bank は .clinerules も見てくれる

update memory bank を行うときに、 .clinerules があればその内容を考慮した Memory Bank が生成されているはずで、より不変な知識は .clinerules に任せるのがよいのだと思う。一方でこれを AI の生成に完全に任せてしまうと、出力が安定しないのでコンフリクト祭り… となりそう。

Cursor の Project Rules との共存

現状だと個人の好みも込みで、 Cursor が共存することが多いと考えていて、実際自分も Cursor の中で Roo Code を動かしている。 Cursor には、少なくとも自分の知る限りでは Memory Bank に相当するものはなく、基本的には Project Rules で AI を制御する形になっている。この運用としてそれぞれの rules 系ファイルを個別に管理するのではなく、ベースとなるものは同一にし、それをそれぞれの形式に加工するスクリプトを用意するような形が想定される。そこで Memory Bank よりは近い性質をもつ .clinerules が管理されているべきだと思う。

逆に一人しか触らない個人での開発ならどうなのか？

これは Cline しか使わないなら、 Memory Bank だけで十分なのではないかと思う。 Memory Bank を運用していく中で、不変なものは .clinerules に蒸留していくような形にするのが良いと思う。

Static Assets の run_worker_first オプション

Fri, 07 Mar 2025 23:05:35 GMT

Cloudflare Workers の Static Assets は、通常ではある URL に対して directory に指定したディレクトリ以下にある静的ファイルのマッチングが優先され、 main の Worker には到達しないが、これを逆にするオプションがある。

Routing

Learn how to configure different architectures for the static assets of your Worker.

developers.cloudflare.com

wrangler.json の場合は次のように設定できる:

{
  "assets": {
    "binding": "ASSETS",
    "directory": "./public",
    "run_worker_first": true
  }
}

このように設定すると、静的ファイルへのアクセスより前に main の Worker を実行できるため、ヘッダーを見て認証するようなことが可能になる。ただし、厳密に言えば静的ファイルへのアクセスがなくなるため、 fallback 的に Static Assets へ Worker からリクエストを投げる必要がある。

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // ....
    return env.ASSETS.fetch(request);
  },
} satisfies ExportedHandler<Env>;

Roo Code の Browser が Dev Container で動かない

Thu, 06 Mar 2025 00:00:00 GMT

普段の開発は基本 Dev Container でやっているので、Roo Code もそのまま Dev Container 前提で触っていたが、動作確認なんかで Roo Code が使おうとするブラウザが動作しないのが気になったので直すことにした。 2025/03/14追記: Cline では PUPPETEER_EXECUTABLE_PATH に相当するものが設定でき、コンテナに chromium をインストールしておけば動作する。最後に記載する。

先に結論

Puppeteer がホストやコンテナの CPU アーキテクチャに関係なく x86_64 を要求するので、 amd64 のライブラリを揃えて動くようにした。

The chromium binary is not available for arm64 · Issue #7740 · puppeteer/puppeteer

Bug description In an ARM based Docker container (or ARM based Linux): npm install puppeteer Error: The chromium binary is not available for arm64. This is related to #6622 which wasn't really solv...

github.com

なんだかんだで Puppeteer を使う機会が一切無かったので全然知らなかった。puppeteer-chromium-resolver のドキュメントに必要なライブラリが書いてある:

GitHub - cenfun/puppeteer-chromium-resolver: Tool to resolve puppeteer and chromium faster

Tool to resolve puppeteer and chromium faster. Contribute to cenfun/puppeteer-chromium-resolver development by creating an account on GitHub.

github.com

これと日本語フォントとして fonts-ipafont-gothic を amd64 でインストールする、これを setup-browser-action.sh としてまとめる:

#!/bin/zsh

# マルチアーキテクチャを有効にする
sudo dpkg --add-architecture amd64

# リポジトリを修正（Debianの場合）
echo 'deb [arch=arm64] http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb [arch=arm64] http://deb.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware
deb [arch=arm64] http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb [arch=amd64] http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb [arch=amd64] http://deb.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware
deb [arch=amd64] http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware' | sudo tee /etc/apt/sources.list

# リポジトリを更新しライブラリをインストール
sudo apt update
sudo apt install -y \
        ca-certificates:amd64 \
        fonts-ipafont-gothic:amd64 \
        fonts-liberation:amd64 \
        libasound2:amd64 \
        libatk-bridge2.0-0:amd64 \
        libatk1.0-0:amd64 \
        libc6:amd64 \
        libcairo2:amd64 \
        libcups2:amd64 \
        libdbus-1-3:amd64 \
        libexpat1:amd64 \
        libfontconfig1:amd64 \
        libgbm1:amd64 \
        libgcc1:amd64 \
        libglib2.0-0:amd64 \
        libgtk-3-0:amd64 \
        libnspr4:amd64 \
        libnss3:amd64 \
        libpango-1.0-0:amd64 \
        libpangocairo-1.0-0:amd64 \
        libstdc++6:amd64 \
        libx11-6:amd64 \
        libx11-xcb1:amd64 \
        libxcb1:amd64 \
        libxcomposite1:amd64 \
        libxcursor1:amd64 \
        libxdamage1:amd64 \
        libxext6:amd64 \
        libxfixes3:amd64 \
        libxi6:amd64 \
        libxrandr2:amd64 \
        libxrender1:amd64 \
        libxss1:amd64 \
        libxtst6:amd64 \
        lsb-release:amd64 \
        wget:amd64 \
        xdg-utils:amd64

これで動作自体はするが、 Roo Code が --no-sandbox で実行できるオプションを用意していなくて、それに対応する必要がある:

File not found · RooCodeInc/Roo-Code

Roo Code gives you a whole dev team of AI agents in your code editor. - File not found · RooCodeInc/Roo-Code

github.com

Sonnet によると --cap-add=SYS_ADMIN をつけてコンテナを起動すればいけるらしく、それらを組み込んだ devcontainer.json は次のようになり、これで動くようになった:

{
    "image": "mcr.microsoft.com/devcontainers/base:1-bookworm",
    "runArgs": [
        "--cap-add=SYS_ADMIN"
    ],
    "postCreateCommand": ".devcontainer/setup-browser-action.sh",
    "features": {
        "ghcr.io/devcontainers/features/node:1": {},
        "ghcr.io/shyim/devcontainers-features/bun:0": {},
        "ghcr.io/devcontainers/features/github-cli:1": {}
    }
}

下にある元の設定と比べて base:1 から base:1-bookworm になっているが、 setup-browser-action.sh と揃えるためで本質的には違いがない。

動かない状態

M2 MacBookAir で OrbStack を使っている。devcontainer.json はこれ:

{
    "image": "mcr.microsoft.com/devcontainers/base:1",
    "features": {
        "ghcr.io/devcontainers/features/node:1": {},
        "ghcr.io/shyim/devcontainers-features/bun:0": {},
        "ghcr.io/devcontainers/features/github-cli:1": {}
    }
}

これで作ったコンテナ内に Roo Code をインストールして Browser を使うと次のようになる:

Error executing browser action:
Failed to launch the browser process!
OrbStack ERROR: Dynamic loader not found: /lib64/ld-linux-x86-64.so.2

This usually means that you're running an x86 program on an arm64 OS without multi-arch libraries.
To fix this, you can:
  1. Use an Intel (amd64) container to run this program; or
  2. Install multi-arch libraries in this container.

This can also be caused by running a glibc executable in a musl distro (e.g. Alpine), or vice versa.

For more details and instructions, see https://go.orbstack.dev/multiarch


TROUBLESHOOTING: https://pptr.dev/troubleshooting

特に指定していないのでコンテナは aarch64:

$ uname -m
aarch64

その他の案

amd64 のコンテナにする

--platform=linux/amd64 としてコンテナ側のアーキテクチャを揃える案。これは過去に VSCode の拡張が動かないものが出てきたので避けたもの。よって採用したくないのと、そもそもビルドがうまくいかなくて早々に諦めた。

puppeteer が自前した Chromium を使うようにする

詳しい説明は下の参考記事を見てもらったほうがよいので割愛するが、次のようなコンテナでいけるか試してみた:

{
    "image": "mcr.microsoft.com/devcontainers/base:1",
    "containerEnv": {
        "PUPPETEER_SKIP_CHROMIUM_DOWNLOAD": "true",
        "PUPPETEER_EXECUTABLE_PATH": "/usr/bin/chromium"
    },
    "postCreateCommand": "sudo apt update && sudo apt install -y chromium",
    "features": {
        "ghcr.io/devcontainers/features/node:1": {},
        "ghcr.io/shyim/devcontainers-features/bun:0": {},
        "ghcr.io/devcontainers/features/github-cli:1": {}
    }
}

これはうまくいかなかった。何が悪いのかちゃんと分かっていないが、 x86_64 で実行しようとする。環境変数を Roo Code が読んでくれない…？

参考にした記事

zenn.dev

Linux machines · OrbStack Docs

Run full Linux machines with your choice of distro, integrated Linux and Mac commands, fast file sharing, and easy setup. Supports Intel emulation, resource efficiency, SSH agent forwarding, and advanced automation via cloud-init or CLI.

docs.orbstack.dev

めちゃくちゃ参考になったので、この記事がまた誰かの解決に役立つと良いと思い残そうと思った。

2025/03/14 追記

Cline では PUPPETEER_EXECUTABLE_PATH に相当するものが設定でき、コンテナに chromium をインストールしておけば動作する。ので、この設定で動作するはず:

{
    "image": "mcr.microsoft.com/devcontainers/base:1-bookworm",
    "runArgs": [
        "--cap-add=SYS_ADMIN"
    ],
    "postCreateCommand": "sudo apt update && sudo apt install -y chromium",
    "customizations": {
        "vscode": {
            "settings": {
                "cline.chromeExecutablePath": "/usr/bin/chromium"
            },
        }
    }
}

Roo Code で GitHub Issue を解決しようとしてくれる Custom Mode を作る

Thu, 06 Mar 2025 00:00:00 GMT

Roo Code は Code や Architect といった標準のモードの他に、自分で Custom Mode を作ることができる。これを gh コマンドと組み合わせれば、 GitHub から Issue を拾ってきて、それを解決するような Custom Mode を作ることが出来そうだったので試した。

docs.roocode.com

GitHub CLI について

docs.github.com

前提

Tier 4 の 3.7 Sonnet (thinking)
Cursor Pro を使うこともある
Dev Container での開発
- features で ghcr.io/devcontainers/features/github-cli を入れている
この時点では精度にはあまり期待していない、参考になる何かができるか手を付けるきっかけになれば嬉しい、というモチベ
- Issue の品質にもバラつきがあるので

動くか試す

issue list と issue view は次のような出力をするので、これを食わせれば Issue が読めそう:

$ gh issue list

Showing 13 of 13 open issues in yaakaito/yaakaito

ID   TITLE                                                             LABELS  UPDATED
#55  注釈は Pop Over で Top Layer に出すようにする                             about 5 hours ago
#54  アイキャッチ画像を最終的に合成する際、目安の線を引く                      about 5 hours ago
#53  モチーフと背景色は、それが何を表しているかの対応表を表示する              about 5 hours ago
....

$ gh issue view 47

アイキャッチ画像は生成に AI が関係していることをわかるようにする #47
Open • yaakaito opened about 11 hours ago • 0 comments



  • 画像の右下に i マークをつけて、「AI が作ったものを人間が加工している」といった旨を表示するようにする
  • GitHub Issue へのリンクを用意して、問題があれば報告できるようにする
  • 専用の Issue テンプレートを用意する


View this issue on GitHub: https://github.com/yaakaito/yaakaito/issues/47

Code モードで gh の使い方を教えながら Issue を解決できるかを試した:

これでもう修正を始めてくれた、えらい。残りはいつもの Code なので割愛。

Custom Mode にする

考えた手順がそのままプロンプトなので完成品、名前は Issue Hunter にした:

You are Roo, a highly skilled software developer with extensive knowledge, specializing in analyzing GitHub Issues, solving problems, and implementing fixes.

1. Run `gh issue list` to check currently active issues
2. Check `.issue-hunter.md` to review issues you have already attempted to fix
3. Run `gh pr list` to check if there are any existing Pull Requests for fixes
4. Select an issue that the user requests, or choose one you can handle if the user doesn't specify
5. View issue details using `gh issue view {id}`
6. Create a detailed plan to accomplish the task based on the issue details. While you should work independently, ask the user clarifying questions if anything is unclear
7. Before making changes, create a branch using `git switch -c fix/{id}`
8. Implement the solution according to your plan
9. When implementation is complete, create a git commit with the following format:

```
{appropriate commit message} fix #{id}
Details of the plan
Details of the plan
Details of the plan
```

10. After `git commit`, push the current branch using `git push origin fix/{id}`
11. After pushing, create a Pull Request using `gh pr create`
12. Write a concise summary of your work in `.issue-hunter.md` - this file is used to track which issues you have resolved
13. Return to the main branch using `git switch main`

これの日本語版も貼っておく、ちなみに「日本語 → Sonnet → 英語 → Sonnet → 日本語」でシステムプロンプトであることを考慮して出力して、とお願いしたもの:

あなたはRooであり、GitHub Issueの分析、問題解決、修正の実装を専門とする高度な知識を持つ熟練したソフトウェア開発者です。

1. `gh issue list`を実行して、現在アクティブなIssueを確認します
2. `.issue-hunter.md`を確認して、すでにあなたが修正を試みたIssueを確認します
3. `gh pr list`を実行し、すでに修正のためのPull Requestがないかを確認します
4. ユーザーが求めるIssueがあればそれを、そうでなければあなたがこなせそうなIssueを選択して解決します
5. Issueの詳細は`gh issue view {id}`で確認できます
6. Issueの詳細を見てタスクを達成するための詳細な計画を立てます。これは基本的にあなたが自立して行うべきですが、内容が不明瞭だったり、質問がある場合はユーザーに明確化のための質問をするべきです
7. 修正を行う前に`git switch -c fix/{id}`でブランチを作成してください
8. 計画に沿って実装を行ってください
9. 実装が終わったら、次のフォーマットで`git commit`してください：

```
{適切なコミットメッセージ} fix #{id}
計画の詳細
計画の詳細
計画の詳細
```

10. `git commit`したら、現在のブランチを`git push origin fix/{id}`でプッシュします
11. プッシュしたら`gh pr create`でPull Requestを作成します
12. `.issue-hunter.md`に今回の作業を簡潔に書き込んでください、これはあなたがIssueの解決状況を把握するために使用するファイルです
13. ブランチを`git switch main`でmainに戻してください

最初は 2 と 3 がなくて、新しい Task になるとまた同じ Issue を直そうとしていたのでやったことを残してもらうようにした、このファイルは gitignore する前提。もし使う場合はパスとか名前はよしなにしてほしい。

元々あと一行「14. 特別な指示がなければ、次のIssueを解決するために積極的に手順1から繰り返し、継続的に問題を解決し続けてください」というのがあったが、動いたり動かなかったりするのと、修正中に作ったゴミが残ったりなんかして、 Git がごちゃごちゃすることがあったのでやめた。連続でいくつか直すのは Task での入力で多分できる。

適当に何か直させる

これで「なんかなおして」とかお願いすると、まだ着手してなさそうな Issue を探して作業を始めてくれる。参考までにこれを書いている時点では gh issue list はこんな感じになっている:

$ gh issue list

Showing 13 of 13 open issues in yaakaito/yaakaito

ID   TITLE                                                             LABELS  UPDATED
#55  注釈は Pop Over で Top Layer に出すようにする                             about 5 hours ago
#54  アイキャッチ画像を最終的に合成する際、目安の線を引く                      about 5 hours ago
#53  モチーフと背景色は、それが何を表しているかの対応表を表示する              about 5 hours ago
#52  倍率を 12x も選べるようにする                                             about 6 hours ago
#51  アイキャッチのモチーフを強制的に選べるように                              about 6 hours ago
#50  背景色候補のトーンを下げる、サンプルを作る                                about 6 hours ago
#49  背景を全く違う色で塗りつぶす機能が必要そう                                about 6 hours ago
#48  コードブロックが長い場合に折り畳めるようにする                            about 9 hours ago
#47  アイキャッチ画像は生成に AI が関係していることをわかるようにする          about 11 hours ago
#46  note/9 が 404 になる                                                      about 1 day ago
#44  Vectroize への登録を差分化する                                            about 7 days ago
#41  投稿は archive として一元化し、タグでカテゴリを管理する                   about 25 days ago
#36  Note の emoji にバリエーションをつける                                    about 1 month ago

なんかなおして

やれそうな Issue を見つけてくる:

直すところは Code モードと大して変わらないので割愛。変更が完了したら、commit して push して .issue-hunter.md を更新してくれる:

PR も作ってくれて、 main に戻ってきて終わり:

出来た Pull request はこれ、ちなみにやることはちゃんと間違えていて、そういうことではないという感じではある:

note/9ページが404になる問題を修正 by yaakaito · Pull Request #65 · yaakaito/yaakaito

イシュー #46 の修正問題 note/9が404エラーになる問題対応内容 web/src/pages/note/9.mdファイルを新規作成 View Transition APIに関する記事内容をイシューの説明から抽出し、適切なフォーマットで作成他のnoteファイルと同様のフロントマターを含めて作成 Closes #46

github.com

他のものも直してほしいのでお願いする:

もっとやって

新しい Issue を探してきて直してくれる、このあと連続でもう一つ直してくれて、合計 3 つの PR を作ってくれた:

出来た Pull request (差分):

Noteの絵文字にバリエーションをつける by yaakaito · Pull Request #66 · yaakaito/yaakaito

イシュー #36 の修正問題 Noteの絵文字がすべて同じ「🖊」で単調だった TIPSやNEWS、MEMOなどの粒度で絵文字を分けたい対応内容各ノートの内容を解析し、適切なカテゴリに分類して絵文字を割り当てるスクリプトを作成カテゴリ毎に複数の絵文字を用意し、ランダムに選択するようにした TIPSカテゴリ（💡, 🔧等） NEWSカテゴリ（📢, 📰等）コードカテゴリ（💻, 🖥️...

github.com

アイキャッチ画像はAI生成に関わることがわかるようにする by yaakaito · Pull Request #67 · yaakaito/yaakaito

イシュー #47 の修正問題アイキャッチ画像がAI生成に関わっていることがユーザーに明示されていない問題報告の手段が用意されていない対応内容 BlogCardとNoteCardコンポーネントにAI生成であることを示す「ⓘ」バッジを追加画像の右下にアイコンを表示ホバー時に詳細情報を表示（「この画像はAIを使用して生成された後、人間が調整したものです」）問題報告用のGi...

github.com

直してほしいやつを直してもらう

例えば「#52 倍率を 12x も選べるようにする」を直してもらいたければ、「倍率のやつ直して」とかで通じる:

倍率選択に12xオプションを追加 by yaakaito · Pull Request #68 · yaakaito/yaakaito

概要 Issue #52 「倍率を 12x も選べるようにする」の修正を実装しました。変更内容アイキャッチ画像エディタの最終出力セクションにある倍率選択のドロップダウンメニューに「12x」のオプションを追加ユーザーが1x, 2x, 4x, 8x, 12x, 16xの6つの倍率から選択できるようになりましたスクリーンショット（なし） fixes #52

github.com

雑感

Issue を整備しておけばそれなりの精度で勝手に直してくれるので、これまで腰が重かったものにも手を出せるようになりそう
- フォーマット化して、曖昧なことを書いていないかなんかを CI で lint させたりして、事前にブラッシュアップできると良さそう
今回何が答えかわかりにくいブログというコードで試しているけど、ガードレールがきちんとしたリポジトリであれば結構精度良く直してくれそう
とりあえず暇なときに動かしておく、とかでも Issue に取り組むきっかけになるのでよさそう

Roo Code の Architect で計画を立ててこのブログをリデザインする

Wed, 05 Mar 2025 00:00:00 GMT

これまでここには自分用のまとめくらいにしか記事を書いていなかったのでデザインもかなり適当だったのですが、前回の記事をきっかけに人が見られるレベルにしたいなと思ったので、 Roo Code とやってみることにした。

前提

Tier 4 の 3.7 Sonnet (thinking)
Cursor Pro を使うこともある

Architect is

Roo Code には実行モードがデフォルトでいくつかあり、その内の一つ、 Cline だと「Plan」と呼ばれているもののはずで、コード生成をせずに設計を行うモード。いきなり実装に入るよりも、こっちで計画を立ててから実装に移るのがよいと言われている。

同一コンテキストであればモードの切替でよいと思うが、今回は全体を書き直させたかったので一回じゃ足りないだろうなと思い、何かしらの記憶領域を使いたかった。こんな感じのフローで進めたい:

Architect モードでどんなデザインにするかを相談する
話した内容をどこかにプランとして保存する
別の Code モードの Task で、プランを元に実装を進めて、進捗を記録する
Content Window が足りなくなったら、それまでの実行結果を持って新しい Task に移動する

先に言っておくと、意図せず Context Window が足りなくなるということが今回なかったので、各タスクは基本的にすべて完遂しているという前提で話が進む。

保存と記録をどうするか

Cline 公式のドキュメントに Memory Bank というものがあって、これは現在のコードベースや進捗状況を書き出しておくことで、それを元に会話を進めることができるという考え方らしい。

docs.cline.bot

そういうのがある、という知識としてはあったので、今回のリデザイン作業をする前にこの Memory Bank のプロンプトは動かしてみていたのだけど、個人的には微妙だなと感じていた。あくまで初学者の自分がそう感じているだけで、使い方が間違っているとか、使いこなせば便利なんだろうなという気はするが、次のような点が気になった:

activeContext が今回一番気になっていたが、更新されるタイミングがイマイチ掴めず
follow your custom instructions / update memory bank みたいなコマンド前提なのがちょっと面倒くさい
多人数での利用に適したものなのか疑問、これは全く感覚が掴めなかったという話

そんな感じだったのでこれを使うのはやめて(というか放置して)、もっとシンプルに plan.md と state.md というファイルを作ってみることにした。前者には Architect モードでの計画を吐き出してもらって、実装のたびに後者を更新していくようなイメージ。リデザインに限らず「Architect で相談 → Code で実装 → 状態を記録 → Code で実装 …」という流れで何かしらを開発するとして、その一連の流れはリポジトリ全体で見ると一時的で個人的なイベントであるため、それを共有するような形にしても嬉しくないんじゃないかなというのもあった。

Architect で計画を立ててもらう

GitHub のブログや CircleCI のブログがいい感じだなと思っていたので、スクリーンショットしてそれを参考にやってもらうことにした。 Cursor を使っているときもこの方法をよく使っていて、実装してもらいたい UI のスクリーンショットを取ってプロンプトに添付していた¹。

文字のプロンプトとしては以下で、これに画像が 2 つ付く感じ。

@/web/ を画像のようなデザインに変更したいので、どういう方針で進めていくかを考えてください
また、次の仕様を満たしてください:

- ダークテーマとライトテーマの両方に対応
- グレースケールを中心としつつも、赤をアクセントとして使っていく
- ブログとノートはトップレベルでは混合させてもよい
    - ただし、大きく表示してよいのはブログだけにする

かなり雑な感じだけど、 Figma なりでデザインがあるわけでもなくなので、話しながら進められればいいかなくらいの感覚だった。そうするとこんな感じでいろいろ出してくれるので中身を確認する。

なにかあったら言ってねと言われるので、計画を見て間違ってそうなところを直してもらう。

単体の記事を表示するヒーローセクションは不要で、4 つの記事を組み合わせるようなコンポーネントを作ってください。
左には大きく最新のブログを 1 つ、右にはブログとノートの区別なく最新の 3 つを表示します。ただし、左と右でコンテンツに重複がないようにします。

計画が更新されてくので、同じ手順とノリで満足するまで繰り返した。だいたい出来たあたりでこんな感じの質問があって、

Roo has a question:
実装プランの詳細ありがとうございます。コンポーネント作成が必要とのことですが、まだAstroプロジェクトにcomponentsディレクトリがないようです。この部分について、どのように進めるべきでしょうか？また、デザインを実装する際の優先順位はどのように考えていますか？

components ディレクトリは作っても構いませんが、 astro contents を採用する予定がないので、それは使わないでください
優先順位はなんでもいいのでお任せします

こう答えたら、実装を始めていいと勘違いしたのか Code モードに切り替えようとしたので一旦止めた。内容としてはこれくらいでよかったので、ついでに plan.md を作ってもらう。

code モードに切り替える前に、ここまでの計画を plan.md にまとめて保存して

するとこんな感じに計画を作ってくれる、長すぎるので折り畳めるようにしたい。

# yaakai.to ウェブサイトリデザイン計画

## 全体コンセプト

- グレースケールをベースにした、赤色アクセントのモダンなデザイン
- ブログとノートを視覚的に区別するレイアウト
- ブログ記事を大きく表示し、ノートをコンパクトに表示
- ダークモードとライトモード両対応
- YouTubeチャンネルページのようなカテゴリ分けのある構造

```mermaid
flowchart TD
    A[ヘッダー] --> B[メタコンテンツセクション]
    B --> B1[humans.txt]
    B --> B2[rss.xml]
    B --> B3[llms.txt]
    B --> C[フィーチャーセクション]
    C --> C1[左大型カード - 最新ブログ]
    C --> C2[右サイド - 最新3記事]
    C --> D[カテゴリセクション]
    D --> D1[ブログセクション]
    D1 --> D1a[グリッドレイアウト]
    D --> D2[ノートセクション]
    D2 --> D2a[グリッドレイアウト]
```

## カラースキーム

```css
:root {
  /* グレースケールパレット - ライトモード */
  --gray-100: #FFFFFF;
  --gray-200: #F9F9F9;
  --gray-300: #F0F0F0;
  --gray-400: #E0E0E0;
  --gray-500: #C0C0C0;
  --gray-600: #808080;
  --gray-700: #505050;
  --gray-800: #303030;
  --gray-900: #121212;

  /* アクセントカラー - 赤色系 */
  --red-500: #E53935;
  --red-600: #D32F2F;
  --red-700: #C62828;

  /* 機能的な色の割り当て */
  --bg-color-level-0: var(--gray-100);
  --bg-color-level-1: var(--gray-200);
  --bg-color-level-2: var(--gray-300);
  --bg-color-level-3: var(--gray-400);
  --bg-color-level-4: var(--gray-500);

  --text-color-level-0: var(--gray-900);
  --text-color-level-1: var(--gray-800);
  --text-color-level-2: var(--gray-700);

  --primary-color-level-0: var(--red-600);
  --primary-color-level-1: var(--red-500);
  --primary-color-level-2: var(--red-700);

  /* コンテンツタイプ識別色 */
  --blog-color: var(--red-600);
  --note-color: var(--gray-600);
}

@media (prefers-color-scheme: dark) {
  :root {
    /* ダークモード用の色の割り当て */
    --bg-color-level-0: #121212;
    --bg-color-level-1: #1E1E1E;
    --bg-color-level-2: #2D2D2D;
    --bg-color-level-3: #353535;
    --bg-color-level-4: #424242;

    --text-color-level-0: #FFFFFF;
    --text-color-level-1: #E0E0E0;
    --text-color-level-2: #BDBDBD;

    --primary-color-level-0: #F44336;
    --primary-color-level-1: #EF5350;
    --primary-color-level-2: #E53935;

    /* ダークモードでのコンテンツタイプ識別色 */
    --blog-color: #FF5252;
    --note-color: #A0A0A0;
  }
}
```

## コンポーネント設計

### 1. ヘッダー
- シンプルなナビゲーション
- サイト名とアイコン
- ブログとノートへのリンク

### 2. メタコンテンツセクション
- humans.txt セクションの表示（現在と同様の表示スタイル）
- humans.md の内容を表示
- rss.xml へのリンクを追加
- llms.txt へのリンクを追加
- メタコンテンツへのリンクを視覚的にまとめて配置

### 3. フィーチャーセクション
- 非対称グリッドレイアウト
- 左側に大きなカード（最新ブログ記事）
- 右側に3つの小さなカード（最新記事）
- グリッドベースで水平スクロールなし

```css
.feature-section {
  display: grid;
  grid-template-columns: 3fr 2fr;
  gap: 24px;
  margin-bottom: 48px;
}

.feature-main {
  grid-column: 1;
  grid-row: span 3;
}

.feature-sub {
  grid-column: 2;
  display: flex;
  flex-direction: column;
  gap: 16px;
}
```

### 4. カテゴリセクション
- 各カテゴリごとのセクション（ブログ、ノートなど）
- カテゴリ名と「もっと見る」リンクを含むヘッダー
- レスポンシブグリッドレイアウト
- コンテンツタイプの視覚的区別

```css
.category-section {
  margin-bottom: 48px;
}

.category-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 24px;
}

.category-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 24px;
}
```

### 5. カードデザイン

#### ブログカード
- 大きな画像/サムネイル
- 赤色アクセントのインジケーター
- タイトル、日付、概要テキスト

#### ノートカード
- コンパクトなデザイン
- グレースケールベース
- 絵文字とタイトルを主体に

## レスポンシブデザイン

### デスクトップ (1024px以上)
- フィーチャーセクション：非対称グリッド (3:2)
- カテゴリグリッド：4列

### タブレット (768px - 1023px)
- フィーチャーセクション：非対称グリッド (3:2)
- カテゴリグリッド：2-3列

### モバイル (768px未満)
- フィーチャーセクション：1列
- カテゴリグリッド：1列

# 実装プラン

## コンポーネント構造について

Astro Contentsは使わず、コンポーネントは以下のように実装します：

1. **src/components ディレクトリを新規作成**：
   - 再利用可能なUI要素をコンポーネントとして実装
   - 各コンポーネントは独立した.astroファイルとして作成

2. **コンポーネント名の例**：
   - `BlogCard.astro`
   - `NoteCard.astro`
   - `FeatureGrid.astro`
   - `CategorySection.astro`

## ディレクトリ構造

```
src/
├── components/     <- 新規作成
│   ├── BlogCard.astro
│   ├── NoteCard.astro
│   ├── FeatureGrid.astro
│   └── CategorySection.astro
├── layouts/        <- 既存
│   ├── global-layout.astro
│   └── blog-post.astro
└── pages/          <- 既存
    ├── index.astro
    ├── blog/
    └── note/
```

## 実装の優先順位

1. **グローバルスタイルの更新**
   - カラースキームの変更
   - 基本レイアウト構造の改善
   - タイポグラフィの更新

2. **コアコンポーネントの作成**
   - カードデザイン
   - グリッドレイアウト
   - セクションヘッダー

3. **トップページの再構築**
   - フィーチャーグリッド
   - カテゴリセクション
   - レスポンシブデザイン対応

4. **各ページの更新**
   - ブログインデックスページ
   - ノートインデックスページ
   - 記事詳細ページ

## 詳細実装ステップ

### フェーズ1: グローバルスタイルとレイアウトの更新

#### 1-1. カラースキームの更新
```mermaid
flowchart TD
    A[web/src/layouts/global-layout.astro] --> B[CSSカラー変数の更新]
    B --> C[ライト/ダークモードの調整]
```

**作業内容:**
- `web/src/layouts/global-layout.astro` ファイルの CSS 変数を更新
- グレースケールベースのカラーパレットを実装
- 赤色アクセントカラーの設定
- ブログとノートの識別色の設定

#### 1-2. 基本レイアウトの更新
```mermaid
flowchart TD
    A[web/src/layouts/global-layout.astro] --> B[コンテナ構造の更新]
    B --> C[ヘッダースタイルの改善]
```

**作業内容:**
- ページ全体のコンテナサイズと余白の調整
- ヘッダーのデザイン更新
- 基本的なグリッドレイアウトの準備

### フェーズ2: コンポーネントの作成

#### 2-1. カードコンポーネントの作成
```mermaid
flowchart TD
    A[src/components/] --> B[BlogCard.astro]
    A --> C[NoteCard.astro]
    A --> D[FeatureCard.astro]
```

**作業内容:**
- `src/components/` ディレクトリを作成
- ブログ用カードコンポーネントの実装
- ノート用カードコンポーネントの実装
- フィーチャーセクション用の大型カードコンポーネントの実装

#### 2-2. セクションコンポーネントの作成
```mermaid
flowchart TD
    A[src/components/] --> B[FeatureGrid.astro]
    A --> C[CategorySection.astro]
```

**作業内容:**
- フィーチャーグリッドコンポーネントの実装
- カテゴリセクションコンポーネントの実装
- 各セクションのレスポンシブデザイン対応

### フェーズ3: トップページの再構築

#### 3-1. メタコンテンツセクションの更新
```mermaid
flowchart TD
    A[web/src/pages/index.astro] --> B[メタコンテンツの表示スタイル更新]
    B --> C[各リンクの配置とスタイル]
```

**作業内容:**
- humans.txt セクションのスタイルを更新
- rss.xml と llms.txt へのリンクを追加
- メタコンテンツをグループとして視覚的にまとめる
- 新しいデザインテーマに合わせたスタイル調整

#### 3-2. フィーチャーセクションの実装
```mermaid
flowchart TD
    A[web/src/pages/index.astro] --> B[データ取得ロジックの更新]
    B --> C[FeatureGridコンポーネントを使用]
```

**作業内容:**
- ブログとノートの記事データ取得ロジックの改善
- 最新記事を取得して、左側に最新ブログ、右側に残りの最新記事を配置
- フィーチャーグリッドコンポーネントを使用して表示

#### 3-3. カテゴリセクションの実装
```mermaid
flowchart TD
    A[web/src/pages/index.astro] --> B[ブログセクションの実装]
    A --> C[ノートセクションの実装]
```

**作業内容:**
- ブログ記事用のカテゴリセクション実装
- ノート用のカテゴリセクション実装
- CategorySectionコンポーネントを使用して表示

### フェーズ4: 各ページの更新

#### 4-1. ブログページの更新
```mermaid
flowchart TD
    A[web/src/pages/blog/index.astro] --> B[グリッドレイアウトの更新]
    B --> C[BlogCardコンポーネントの使用]
```

**作業内容:**
- ブログインデックスページのレイアウト更新
- カテゴリフィルターの追加（将来機能）
- BlogCardコンポーネントを使用した記事表示

#### 4-2. ノートページの更新
```mermaid
flowchart TD
    A[web/src/pages/note/index.astro] --> B[グリッドレイアウトの更新]
    B --> C[NoteCardコンポーネントの使用]
```

**作業内容:**
- ノートインデックスページのレイアウト更新
- NoteCardコンポーネントを使用した記事表示

### フェーズ5: 詳細ページとレスポンシブ対応

#### 5-1. 記事詳細ページの更新
```mermaid
flowchart TD
    A[web/src/layouts/blog-post.astro] --> B[詳細ページのスタイル更新]
    B --> C[関連記事セクションのデザイン改善]
```

**作業内容:**
- 記事詳細ページのレイアウト更新
- Markdownスタイルの調整
- 関連記事セクションのデザイン改善

#### 5-2. レスポンシブデザインの最適化
```mermaid
flowchart TD
    A[すべてのコンポーネント] --> B[モバイル対応の強化]
    B --> C[タブレット対応の調整]
    C --> D[大画面対応の最適化]
```

**作業内容:**
- すべてのコンポーネントとページでのレスポンシブデザイン強化
- モバイルファーストでのスタイル調整
- メディアクエリの統一と最適化

## 実装の注意点

1. **段階的アプローチ**：一度にすべてを変更するのではなく、段階的に実装して各フェーズで確認する

2. **コンポーネント分離**：再利用可能なコンポーネントを作成し、コードの重複を避ける

3. **型の活用**：TypeScriptの型を適切に利用し、データの整合性を確保する

4. **パフォーマンス考慮**：画像最適化やCSSの効率的な構造化を考慮する

5. **アクセシビリティ対応**：対比の確保、キーボード操作、スクリーンリーダーのサポートなど

6. **テスト**：各フェーズで異なるデバイスサイズやブラウザでのテストを実施

内容が合っているかを確認する、多分いい感じ。 plan.md も作ってもらう。

タスクが完了するごとに、plan.md をどこまで進めたかを state.md として書き出すようにして

**最終更新**: 2025年3月4日

## 概要
yaakai.toウェブサイトをモダンなグレースケールベース + 赤色アクセントのデザインに更新するプロジェクト。ブログとノートを視覚的に区別するレイアウトを実装し、YouTubeチャンネルページのようなカテゴリ分けを導入します。

## 現在の進捗状況

### フェーズ1: グローバルスタイルとレイアウトの更新
- [ ] 1-1. カラースキームの更新
- [ ] 1-2. 基本レイアウトの更新

### フェーズ2: コンポーネントの作成
- [ ] 2-1. カードコンポーネントの作成
- [ ] BlogCard.astro
- [ ] NoteCard.astro
- [ ] FeatureCard.astro
- [ ] 2-2. セクションコンポーネントの作成
- [ ] FeatureGrid.astro
- [ ] CategorySection.astro

### フェーズ3: トップページの再構築
- [ ] 3-1. メタコンテンツセクションの更新
- [ ] 3-2. フィーチャーセクションの実装
- [ ] 3-3. カテゴリセクションの実装

### フェーズ4: 各ページの更新
- [ ] 4-1. ブログページの更新
- [ ] 4-2. ノートページの更新

### フェーズ5: 詳細ページとレスポンシブ対応
- [ ] 5-1. 記事詳細ページの更新
- [ ] 5-2. レスポンシブデザインの最適化

## 次のステップ
1. グローバルレイアウトのカラースキームを更新
2. 基本レイアウト構造の改善
3. コンポーネントディレクトリを作成し、初期コンポーネントを実装

## 備考
- 計画は [plan.md](./plan.md) に詳細に記述されています
- デザインはグレースケールベースに赤色アクセントを組み合わせたモダンなスタイル
- ブログとノートは視覚的に区別されるデザインを採用
- メタコンテンツ（humans.txt、rss.xml、llms.txt）はトップレベルでグループ化

それっぽいのが出てきた。そして実装に移ろうとするので、待てして Task を引き継ぐためのプロンプトを考えてもらう。

実装してもらう

教えてもらったプロンプトを少し変更してして、@ でファイルを読むようにした。

@/web/plan.md  に記載された計画に従って、yaakai.toウェブサイトのリデザイン実装を進めてください。まずは @/web/src/layouts/global-layout.astro のカラースキーム更新から始め、計画の各フェーズを順番に実装していってください。各ステップが完了するたびに @/web/state.md を更新して進捗を記録してください。最初に計画と現在の進捗状況を確認して、実装を開始してください。

プロンプトに plan.md がちゃんと含まれている図:

確認できたみたいで、計画されていたカラースキームの変更から実装が始まっていく：

すべては貼れないので一部を抜粋すると、計画された順に実装を進めていこうとしていることがわかる:

ただ、 state.md はというと↑の画像くらいのタイミングで進捗を更新してほしかったが、今回のプロンプトだとそれは叶わなかった。こんな感じに最後にまとめてこの Task でやった分を更新してくれた:

Context Window が足りている分にはこれでも構わないが、自分はそれが途切れたときに state.md からある程度状態を復元できることを期待していたので、もっとフェーズを進めるごとにガンガン書き込んでほしかった。 Web の情報を見ていると、そういう動きをしているものもあるように思うので、これはまたあとに試す予定。

あとは同じような手順で、新しい Task を作るときは plan.md と state.md を読み込み更新しながら実装を進めていった。実際どの程度の効果があったかを説明するのは難しいが…、以前にやったときは「今お前が壊したそれ、この前お前が直したじゃん」みたいなことがあったけど、そういう手戻りみたいなことはなかったように思う。

CSS をうまく書けないので覚えてもらう

そういう話題に関連することとして、ミクロな話だと少し複雑な CSS を頑張って実装しても次の瞬間には忘れて破壊する、というのがあった。具体的にはアイキャッチを 2 つのコンテナを跨いでいるように見せるという実装。

これをなんとかして伝えようとしているのだけどまぁうまくいかない。で、最終的にはこれは自分が手で実装することにした。そこまではよいのだけど、問題は次にその周辺を触ったときに、必ずその実装が破壊されて Task が完了するごとに戻っていた。これを解決しないと先に進めないので、実装方針を説明して plan.md や state.md に書いてもらう、というのを試した。

アイキャッチが記事本文側の要素に少しずれているような視覚効果を実現します。
あなたはいままでこれの実装を何度も失敗しているので、私がいう実装方法を覚えてください。

1. .article-header の bottom の padding や margin  を削除して、アイキャッチの下が .article-header の終端と合うようにします
2. .eyecatch-container の兄弟として新たな要素を挿入します、これは記事側と同じ背景色を持ちます
3. この要素を z-index で .eyecatch-container より下にした状態で、 position: absolute; で高さ 80px を持ちつつ、.article-header の終端に合うよう固定します

なるべく頑張って実装を説明した、これを入れたのはぶっ壊れたあとなので、 AI が自身でこの実装を修正する必要があった。この指示はかなりうまくいって、過去に実装された事実があるとはいえ、望んでいたものが改めて AI によって実装された。

その後 plan.md や state.md を更新してもらうと、それらを含めている限りはここに関する手戻りは発生していないように思えた。えらい。

雑感

計画を吐き出すのは良さそう

plan.md は結構いいように思えたので使っていきたい。 state.md はどのくらい効果があったのか肌感がない、わざわざ分ける必要はないかも。

個人用のメモスペースがほしい

plan.md なんかを自由に作れるスペースがリポジトリ内にほしい。AI との会話の成果物を一時的に保存する場所が gitignore されてリポジトリに確保されているといいなと思った、今回は commit してしまったが…。先にも書いたが、全体で共有したいルールがある一方で、個人が一つの作業で使う一時記憶ファイルを全部 commit したいとはならなさそう。そのファイル自体もバージョン管理したいという気持ちもあるので、 submodule なのか…？

複雑なコードは個別の取説を置きたい

マスターデータとなるデザインデータなんかが存在しない中では仕方ないことなのかもしれないが、 HTML + CSS な UI 構築に関しては自分が手を出さないといけないことが多い気がしている、もちろん詳細なデザインは妥協しているが。今回のような内容をすべてプロンプトに含めるわけにもいかないので、コンポーネントのような単位でその実装を説明した取説.md を横においておき、コンポーネントを触るときはその取説を参照させるような仕組みが出来るといいのかもしれない。と思っていたけど、大抵はコメントとして残しておけば解決する話なのかもしれない。

Footnotes

添付という表現が合っているのかはわからない ↩

ドット絵なアイキャッチを AI で作る機能を Roo Code で作ってみた雑記

Sun, 02 Mar 2025 00:00:00 GMT

ドットなアイキャッチを作りたいとずっと思ってはいたので、 Roo Code を本格的に触る題材として作った。最初の方の感想はその時にしか残せないので、さらに進む前にその過程のメモやら雑感やら考えていたことを書いたもの。この記事のアイキャッチはデバッグに使っていたら愛着が湧いてしまったサイっぽいキャラクター。

前提

AI Coding が初めてとかではなく、 GitHub Copilot の β に始まり Cursor Pro は 1 年くらい使っているし、 Cline 系も初めて触るとかではない
Tier 4 の 3.7 Sonnet
素の Roo Code でどんなものかを試したかったので、 Code で書く以外は何もしていない、 rules やプロンプトをカスタマイズしていない
一部は Cursor を使っている

実装過程

パッとこうすればいいがあったわけではないので、ざっくりとした枠組みから作りはじめた。ベースとなるコードは前回作った関連記事のアプリで、新しく作るのも面倒なのでここに継ぎ足す形に。

Workers AI を利用して、アイキャッチ画像を生成するようにします。まずは、どんな画像が作れるかを検証するための簡単アプリを  related-aritcles-worker に機能追加する形で作成してください。
以下の仕様を実現してください:

- `/create_eyecatch` エンドポイントを作成し、受け取った記事の本文から Workers AI を用いて画像を生成します
    - モデルには `@cf/black-forest-labs/flux-1-schnell` を使用します
    - モデルのドキュメントはこれです: https://developers.cloudflare.com/workers-ai/models/flux-1-schnell/
- index.html に記事の本文を送信できるフォームを新たに作成し、画像が生成できたら表示してください

とりあえず記事をそのまま Workers AI の画像生成に投げ込んでみた、それっぽいアプリは出来るが、生成がうまくいくはずもなく文字数オーバー。

ここであった主なやりとり:

dev-server が起動できない
- Dev Container で動かしているので wranlger の起動に --ip が必要で、 package.json の script には書いているんだけど頑なに無視する、 rules で制御できるといいんだろうか？
ブラウザが起動できない
- ちゃんとわかってないが Dev Container 使っているのでホストとのアーキテクチャの違いでうまくいっていないみたいな話、多分私が悪い

画像生成をキーワードで行うようにする:

`/create_eyecatch` での画像生成フローを改善します、以下のフローを実現してください。

- 画像生成より前に、 Text Generation なモデルを通して、記事からキーワードを抽出します
- モデルは @cf/meta/llama-3.3-70b-instruct-fp8-fast を使ってみてください: https://developers.cloudflare.com/workers-ai/models/llama-3.3-70b-instruct-fp8-fast/
- 抽出したキーワードと以下の固定のプロンプトを組み合わせて 2000 文字以内のプロンプトを @cf/meta/llama-3.3-70b-instruct-fp8-fast に作成させます
    - 「ブログのアイキャッチ、背景は単色、人間を含まない、アニメ調」
- 最終的なプロンプトを使って画像を生成します

実装自体は意図通りにやってくれる、ただし意図した画像はでない。プロンプトがゴミなので当たり前すぎる話ではある。ここでなんとなく Open AI の DALL-E を使ってみたくなったので、切り替えてみる。

現在画像生成を Cloudflare の Workers AI で行っていますが、これがうまくいっていないので OpenAI のものに置き換えます。

- プロンプト作成部分は現状を維持します
- 画像生成を DALL·E 3 を使った実装に置き換えてください
- APIKEY は後ほどこちらで設定するので env に OPENAI_API_KEY が設定されている前提で進めてください

サイズ固定が出来るようになって(Workers AI でも出来るものはある)、出力が安定した気がするがほしい感じの画像はまあでない。

ロジックを見直す

記事内のキーワードからそれっぽい画像を作るのはなかなか厳しいことがわかったので、別の方法を考えた。オライリーっぽい感じで、キーワードと動物を関連付けるのはどうかなと思いつつ適当に Sonnet と話していたら Sonnet もそう言っていたので、そうすることにした。カテゴリごとに動物と背景色をざっくりと決めて、それをベースに作ってもらえるようにお願いするプロンプトを Sonnet と考える。

最終的にこんな感じに、オライリーのぱｋリスペクト、メンダコ(dumbo-octopus)は適当にメモにかわいいとか書いてたら Sonnet が入れた:

`/create_eyecatch` の既存のキーワード抽出および画像生成コードを活用・改良し、技術キーワードに対応するドット絵動物キャラクターをベースとしたブログ記事用アイキャッチ画像を生成するシステムを完成さてください。

## 実装内容
1. キーワード-動物マッピングシステムの拡張
以下のマッピングテーブルを既存コードに組み込む：

const techAnimalMap = {
  "cloudflare": { animal: "alpaca", backgroundColor: "#F38020" },
  "ai": { animal: "owl", backgroundColor: "#8A2BE2" },
  "javascript": { animal: "rhino", backgroundColor: "#F7DF1E" },
  "typescript": { animal: "guanaco", backgroundColor: "#3178C6" },
  "html": { animal: "koala", backgroundColor: "#E34F26" },
  "css": { animal: "fish", backgroundColor: "#1572B6" },
  "database": { animal: "dumbo-octopus", backgroundColor: "#336791" }
};

2. キーワード抽出ロジックの強化

既存のキーワード抽出コードを利用し、記事内容から上記に定義されたキーワードの出現頻度を分析
最も関連性の高いキーワードを特定するロジックを追加
複数の関連キーワードがある場合の優先順位付けメカニズムを実装

この辺から画像生成 AI に投げるプロンプトを私が読まなくなったので、全部英語に変えてもらった。プロンプトに更に注文をつけていく:

画像生成プロンプトを次のように改善して

- 8bitゲーム風のレトロな作風に
- キャラクター以外のアイコンやテキストを極力含まない

プロンプトを更に改善します

- キャラクターのドット絵には黒い縁をつける

他にも色々投げた気がしますが、かなりいい感じの画像が返ってくるようになった。最終的なプロンプトのコードはこんな感じ:

const variations = [
    "cute and playful",
    "simple and minimalist",
    "detailed and expressive",
    "cheerful and colorful",
    "cool and stylish"
];
const imageResponse = await openai.images.generate({
    model: "dall-e-3",
    prompt: `Create an 8-bit retro game style pixel art of a ${animal} character representing the concept of ${selectedTechKeyword} and ${keywordsString}.
    The character should be centered on a solid ${backgroundColor} background.
    Style: Classic 8-bit NES/Famicom era pixel art, extremely limited color palette (4-8 colors maximum), ${variations[index]}.
    IMPORTANT: The ${animal} character MUST have a black outline/border around it - this is essential for the retro game look.
    The black outline should be exactly 1 pixel thick and should completely surround the character.
    The ${animal} character should be the ONLY element in the image - no icons, symbols, text, UI elements, or any other objects.
    Make it look like a character sprite from an 80s video game with sharp pixels, no anti-aliasing.
    The final result should be clean, minimalist, and instantly recognizable as an 8-bit game character with a distinct black outline.
    The final image should be exactly 64x64 pixels in size.`,
    n: 1, // DALL-E 3では1枚ずつ生成
    size: "1024x1024", // DALL·E 3で利用可能なサイズ
    quality: "standard",
    response_format: "b64_json",
});

ネガティブっぽいプロンプトは書いても聞いてくれないどころか、書くとほぼ含めてくるようになるのでやめた。 backgroundColor はだいたい無視される。これを 5 リクエスト同時に投げて 5 枚づつ作るようにしている。

ちなみに適当に検証したタイミングで画像生成はやめて、開発中は適当に作ったものに固定すればよかったが、頭が回らずに無駄に $10 くらいクレジット溶かした(戒め1)。あとこんな感じに、ちょっとうまくいったな！と思ったタイミングで絶対に git commit した方がいい(戒め2)。

ドット絵にする、地獄の始まり

この手の画像の生成をやったことがある人は知っていると思うが、生成 AI が作るドット絵はドット絵ではない。わからないと何を言っているんだという感じだが、この記事のサムネの元になった画像を見てみるとわかりやすいと思う:

パット見拡大されたドット絵に見えるが、斜めに切れているドットがあったり、1ドットの中に複数の色が存在したりしている。目とか耳を見るとドット絵としてはまぁない状態になっていることがわかりやすいはず。これを補正して、うまくドット絵にするのが目標。ネタバレするとすべて機械化することは諦めて、最終的には人間が細かい修正をする形に落ち着いた。

さて、これをどう修正していくかというと、まずは範囲選択 → 選択した範囲を 128x128 px のドット絵と見立てる → それぞれのドットを一番多い色で塗りつぶす、というのを考えた。

自動生成したアイキャッチ用画像に簡単な加工が出来るようにします。これは、ブログ全体での画像のテイストをなるべく揃えるために必要な作業です。
次のような加工をしたいと考えています:

- 背景色を透過処理
- 生成された画像から、アイコン部分だけをユーザーが範囲選択して切り抜き
- 切り抜いた画像をニアレストネイバー法を用いて 128x128 に縮小
- 4倍である 512x512 に拡大、1ドット辺り 4x4 を利用する状態にする
- この画像を 1200x630 のキャンバスの真ん中に配置する
- キャンバスの背景を指定された 1 色で塗りつぶす

これを次のようなフローで実現したいと考えています:

- `/create_eyecatch` で候補となる画像を複数枚生成
- クライアントでユーザーが範囲指定して切り抜きを行う
- 縮小、拡大、補正を行ったキャラクターをユーザーが確認できる形で出力
- ユーザーが決定したら、1200x630のキャンバスに配置し、アイキャッチとして出力する

各ステップでキャンセルして先頭に戻せるようにしてください

結論からいうとこれは全くうまくいかなかった。望む状態になるよう何度か修正を加えたが、範囲選択ができ、切り抜きを行って 128x128 に縮小する… というところまではいくが、その画像が綺麗ではない。そもそも生成された画像のドットのサイズがまちまちなので、固定値で出来るようなものでもなく、という感じ。一方で全体の UI とフローというか、要素の配置があまりにも適当すぎる(これは指示を一切していないのも悪いが)ことを除けば、操作自体はそれっぽくできる、すごい。ここで作ったドット絵化のロジックはすべて消えているが、 UI の枠組みはここで作ったものを最後まで使うことになった。

次にグリッドに区切ってそれぞれのドットを一番多い色で塗りつぶす、というのを考えた。イメージとしてはこんなの:

index.html へ画像の加工機能を実装します、これは `/create_eyecatch` で生成された曖昧なドット絵(Pixel Art)をきれいなドット絵に加工し、最終的に 1200 x 630 のサイズにします。

## 前提
- `/create_eyecatch` で生成される画像は 1024x1024 px です
- そこに、拡大された 64x64 px 程度のドット絵が書かれています
- ただし、ドット絵としては歪みもある画像になっています
     - 例えば、拡大された一つの Dot を複数の色が構成しています
     - ドット絵には存在しないはずの、円形の Dot が存在します

## 実装する機能のフロー
ドット絵として不正な Dot を補正して、ドット絵を完成させます。

1. まず返却された複数の画像から一つをユーザーが選択します
2. 選択された画像にグリッドを表示します、このグリッドは 8 x 8 pxを 1 dot として扱います、言い換えると全体を 128 x 128 px のキャンバスだと見立てるということです
3. グリッドの大きさはスライダーでユーザーが調整できるようにします
4. ユーザーがグリッドのサイズを決定したら、画像を変更する処理に入ります
5. 処理した画像を出力します、1200 x 630 のキャンバスにはまだ入れる必要はありません

## 画像処理の詳細
ユーザーが決めたグリッドにそって、Dot の塗りつぶしを行います

- グリッドで区切られた Dot の中で、最も多く使われている色を計算します
- その色で、その Dot をすべて塗りつぶします
- 使った色を記録しておきます
- すべての Dot を塗りつぶしたあと、使った色の数が 16 種類以上ある場合、色を少なくする処理を行います
      - 近い色をまとめ、16 種類にします
      - まとめられた色を、まとめた色で置き換えます
      - 縁の装飾のため真っ黒(#000) は必ず残します
      - 最終的な色の分布が、同じ系統の色に偏らないようにしてください

この処理を行うことで、例えばグリッドのサイズが 8x8 px であれば、1024x1024 の画像が 128x128px のドット絵となることを期待します。

色の絞り込みのルールを変更します。

- 基本的には、使われている回数が多い順に採用し、16 色に収めます
- 人間が識別できない濃淡の差がある色がある場合は、それをまとめます
- この中に、四隅のそれぞれ 4 Dot の色は含まないでください
- 四隅の 4Dot と極めて近い色を持つ Dot はすべて同じ色にします

'related-articles-worker/public/index.html' (see below for file content) に実装されている画像編集機能をさらにパワーアップします。
既存のドットの補正、色の補正の処理が終わったあと、ユーザーがさらに修正を行い、最終的に 1200 x 630 の画像として出力します。
以下の機能を追加してください:

- 補正が終わった画像に対して、使われている色を利用して 1 Dot 単位の変更が出来る機能の追加
- 補正が終わった画像に対して、使われている色を利用して連なっている同色をすべて塗りつぶす機能の追加
- その後、画像の4隅の色と同じ色で塗りつぶした 1200x630 のキャンバスを用意し、任意の位置に加工済みの画像を配置できるようにする
- 背景色を変更できるようにする

## ユーザーによる画像の補正

- 利用している 16 色のパレットから、任意の色を選んで、
     - クリックした Dot をその色に置き換える事ができる
     - 連なっている同色を塗りつぶすことが出来る
          - 塗りつぶしツールを実装する

1 回では不足していたので、細かい修正依頼とかはしつつも大まかに 3 つのプロンプトで機能全体ができた。これはこの時点でかなりいいものが出てきていて、なるべく脳をプロンプトに dump したかいがあったなと感じた。

これにグリッドのオフセットを付け加えたり、 Undo が出来るようにしたり、というのを対話で雑に加えていった。 Undo を作っている途中で一度コンテキストが足りなくなったので、新しいプロンプトで次の指示をしたらわりと察してやってくれた:

@/related-articles-worker/public/index.html にはドット絵を編集する機能がありますが、 undo 機能を実装する途中で止まってしまっています。
undo 機能を完成させてください。

- 10 回まで undo が出来る
-  ctrl + z をショートカットに設定する

このあたりから結構バグ修正というか、動作して気に入らなかったり、動いてなかったりというのを修正することが増えた。あと、この機能の実装を全部 index.html 1 ファイルに詰め込んでいたので、 1 回で使うコンテキストの量があからさまに多くなってきた。

バグ修正の基本的なやりかたとしては、 UI が関わるものは気に入らない部分を SS して、文句と一緒に投げていた。これで基本的には解決してくれる。

唯一「グリッドと画像がずれる」という問題をどうしても Roo Code では解決できなくて、Cursor と解決した。

この辺はいつもどおり Dev Tool からおかしい CSS やら調べたりということしていて、だいたいわかったところで原因がありそうな行を Cursor に投げて直してもらった。 Cursor で直したものは、動作の不具合としてはこれともう一つ。そっちは多分 Cursor でも出来たが、だいたい検討がついていたので Cursor に投げたほうが早いよなとなった。

実装をさらに進めていって、最終的な出力を調整出来る段階まで来たので、細かい位置やドットの大きさを指定できるようにしたい:

@/related-articles-worker/public/index.html のドット絵編集機能を改善します。最終的にアイキャッチとして 1200 x 630 px のサイズで画像を出力します。
以下の機能を実装します:

- 画像の倍率を調整する機能
- 画像の位置を中心からのオフセットで調整する機能
- 選択した色をすべて背景色として扱う機能

## 倍率を調整する機能

この編集機能はグリッドの大きさを設定することができます。
例えば 16px のグリッドを設定した場合、ドット絵として見た場合は 16x16 px が 1 ドットとして扱われるため、16倍に拡大された画像ということになります。
この倍率を最終的な出力では自由に調整できるようにして、画像の大きさを調整します。

次のように実現します:
- 1x 2x 4x 8x 16x のような刻みで倍率を選択出来るようにする
     - この倍率は、元画像からの倍率ではなく、ドット絵を 1 ドット = 1x1px に正規化した場合の倍率です
     - 例えば、16px のグリッドで作成された場合も 8x を選んだのであれば 1 ドットが 8x8px のグリッドで構成されるドット絵になります


## 選択した色をすべて背景色として扱う

最終的な出力の背景を単色としたいので、同一の色で塗りつぶす必要があります
加工中の画像の背景色はランダムなため、パレットから背景色として扱う色を複数個選べる必要があります
選んだ色と、1200x630 を確保して生まれた余剰部分の色をすべて同じにして、単色での背景を実現します

これだとドット絵をそのまま引き伸ばして悲しい感じの画像になっていたので、間違っているよといったら理解してくれた:

@/related-articles-worker/public/index.html でのドット絵編集の最終段階である 1200 x 630 でのアイキャッチ出力部分を改善します。
倍率を変更する際に、元々のグリッドと倍率が異なると色の境界がぼやけるようになっています。これは間違った実装です。
画像の引き伸ばしではなく、ドットのサイズのみを変更します。

アップロードと配信部分を作る

生成するだけで配信をしていないので、作った画像を記事に関連付けて取れるようにする機能を足す。

@/related-articles-worker/src/index.ts にアイキャッチ画像を配信する機能を追加します。アイキャッチ画像は @/related-articles-worker/public/index.html で作成できるようになっています。
次のフローを実装してください:

1. `/registier` で登録されたとき、これまでの処理に追加して、id と本文の内容をセットで KV へ保存します
2. このとき、まだアイキャッチは作られていません
3. index.html で画像生成を開いたとき、まだアイキャッチのない記事の一覧を表示します
4. 記事を選ぶと、対象の id を `/create_eyecatch` に送り、既存のフローでアイキャッチを作成します
5. 作成したアイキャッチをアップロードするエンドポイントを新たに実装し、そこへアイキャッチを送信します
      - また、id を指定して画像をアップロードする方法も同時に用意してください
6. `/eyecatch?id=${id}` で、登録したアイキャッチが画像として返ってくるようにします

データストアが必要であれば、 Workers の KV を利用してください。

特に間違いもなく一瞬で終わる、 index.html がでかすぎて一度途切れたが、「以下のプロンプトではじめた実装の続きをしてください」という指示で同じプロンプトを貼り付けたらうまいことしてくれた。直接アップロードする機能とかも適当に開発させて終わり。書くことが特にない、こういうのが得意なのはそれはそうという感じ。

雑感

まあ安くはない

差額で見た感じ、今回の機能を作るのに $25 くらいかかっていた。ここにすべてのプロンプトを載せているわけではない。土日の可処分時間でやったもので、全部自分で書いたらこうはならなかったなと思うと時間を買えた感覚はあるのだが、今後の趣味の開発がこのペースで進むとして単純に 4 週で月 $100 + α。ここに Cursor Pro と Claude Pro 、API と叩いているツールもろもろの利用料が乗ってなんやかんやで AI に掛かる費用が月 $200 くらいになるのかと思うとなかなか。

ただ、今回ちゃんとやるために Tier 4 に引き上げたが、 Tier 4 未満の Roo Code は考えられないのでやるならまず Tier 4 にした方がいい。低い Tier で使ったこともあり、そのときは微妙という感想だった。

自分でも曖昧な部分の開発が重い

これはわかっていた話というか、別に普段の開発でも変わらないところ。今回でいうとドット絵の編集。完全に人間がやる場合と比べて、とりあえずプロンプトを書けば何かは出てくるので、それを触ってみて「やっぱだめだよな」が気軽にできるのはよかったと思う。ので、別に AI も得意ではないけど、人間がやる理由にはならないとは思った。困ったらそれこそ Chat で相談とかでもよい。ただ、これをやるのに、後述のセーブポイントはまじでたくさん作ったほうがいいと思った。

コンテキストでかすぎ問題

これは index.html にすべての実装を乗せていったのが完全に悪いのだけど、最後の方は 2500 行程度になって 3 回往復したらコンテキストが足りなくなる、みたいになっていた。後で実際のやりとりを除いてみると、ほぼ毎回 index.html をめちゃくちゃ送っている、でかい。ファイル指定しているからそりゃそう。

今回これを回避するのに、前のプロンプト貼り付けて「多分続きまでやってるからなんとかして」みたいな指示をしていた。この進め方自体の是非はともかく、 Roo Code は結構察して進めてくれるので、素直にすごいなと思った。

コンテキストが足りるようにコードを適切に分割しろという話ではあって、コードのファイルを分ける基準が今後はわりとここに関係してきそうだなと思った。今回 rules なんかは全く使っていなくてこれなので、改善できるんだろうなぁとは思いつつも、これ以上にコンテキストに何かを入れることが出来るのか…? という気持ちが強い。

セーブポイントをたくさん作れ

git commit をたくさんしろ、というのとほぼイコール。少しでも期待した動作になったり、進捗が出たと思ったらすぐに commit する癖をつけるのがいいと思った。ここまでをなしにして実装をやり直したい、と思うことが結構あって、その時点で commit がなくて Roo Code の戻すのをお願いしたりしていた。虚無。

プロンプトは適当でもわりとなんとかなる

ここの機能を実装したいときの指示書、みたいなものは結構適当でもいいなという感覚がある。最悪対話で修正すればよくて、これは Cursor でもそう感じていた。ある程度フォーマット化されているのがいいとは思いつつも、曖昧なことやノイズが入っていなければなんとかなる、という印象。それよりもコードベース全体を理解させることの方がはるかに重要だろうな、という感じ、そりゃそう。今回はほぼすべてが index.html だったので、逆にそこは解決されていた感があった。

デザイン適当すぎ問題

これは何も指示していないのがだいたい悪いとは思うんだけど、誰が使えるんだその UI みたいなのが平気で出てくる、基本縦に長過ぎる。

pnpm の Catalogs を使って monorepo 内のバージョンを統一する

Fri, 28 Feb 2025 12:28:22 GMT

monorepo を運用していると、パッケージごとに参照しているライブラリのバージョンが異なっていて、結果として動作不良やビルドエラーにつながるケースがあります。こういった状態を回避する方法として pnpm v 10 で導入された Catalogs 機能が使えます。

Catalogs

pnpm.io

最近 dependabot も対応しました。

Dependabot now supports pnpm workspace catalogs (GA) - GitHub Changelog

Starting today, Dependabot offers full support for pnpm workspace catalogs. pnpm workspace catalogs are widely used in monorepos, and improper dependency handling can lead to: Broken dependency trees due to…

github.blog

Catalogs では、monorepo の定義ファイルである pnpm-workspace.yaml に利用したいバージョンを記載しておくことで、各パッケージからは catalog: でそれを参照することができます。例えば React のバージョンを 19.0.0 に統一したい場合は次のようにします。

pnpm-workspace.yaml:

catalog:
    react: 19.0.0

packages/foo/package.json:

{
  "dependencies": {
    "react": "catalog:"
  }
}

packages/bar/package.json:

{
  "dependencies": {
    "react": "catalog:"
  }
}

こうすると packages/foo でも packages/bar でも、同じ React 19.0.0 が利用できるようになります。

CSS の attr が content と以外でも利用可能に

Sun, 23 Feb 2025 20:04:49 GMT

Chrome 133 以降で、これまで次のように content: attr(data-text); のような形でしか利用できなかった attr() が、それ以外のものにも適用出来るようになりました。

<div class="code" data-language="ts"></div>
<style>
  .code::before {
    content: attr(data-language); // これまでは実質この用途専用だった
  }
</style>

例えば汎用的なコンポーネントを作るときに、外から width や height 、 color を渡したいケースがあります。これをアップデートされた attr() でこのように書くことができます。

<div class="box" data-width="400" data-height="400" data-color="#ff00ff"></div>
<style>
.box {
  width: attr(data-width px, 200px);
  height: attr(data-height px, 200px);
  background: attr(data-color type(<color>), red);
}
</style>

attr() の引数は 2 つで、前者は attrbiute 名と型を指定できます、 px を指定すると attribute は数値として扱われ、 type(<color>) ではそれを色として扱うことを伝えています。 2 つ目の引数は fallback で、 attribute が存在しなかった場合にその値が選択されます。

Refs

CSS attr() のアップグレード  |  Blog  |  Chrome for Developers

カスタムプロパティを含む任意の CSS プロパティで attr() を使用できるようになりました。文字列以外のデータ型に値を解析できます。

developer.chrome.com

CSS attr() gets an upgrade

You can now use `attr()` with any CSS property — not just content – and it can parse values into data types other than <string>.

www.bram.us

attr() - CSS | MDN

attr() は CSS の関数で、選択した要素の属性の値を取得し、それをプロパティ値で使用するために使用されます。これは、 var() 関数が独自のプロパティ値を置き換える方法と似ています。擬似要素で使用することもでき、その場合は擬似要素を作る元になった要素の属性値が返されます。

developer.mozilla.org

Cloudflare Vectorize と Workers AI で関連する記事を作ってみる

Sun, 23 Feb 2025 00:00:00 GMT

このブログは SSG したものを GitHub Pages にデプロイしているのですが、 Cloudflare Vectorize と Workers AI を使うと関連記事を表示することができそうだったので作ってみました。

このブログのリポジトリにある Worker として実装しています：

yaakaito/related-articles-worker at main · yaakaito/yaakaito

Contribute to yaakaito/yaakaito development by creating an account on GitHub.

github.com

チュートリアルと被る部分も多々あるので、そちらも参考にしてください。

Vectorize and Workers AI

Vectorize allows you to generate vector embeddings using a machine-learning model, including the models available in Workers AI.

developers.cloudflare.com

Workers AI による埋め込みベクトルの生成

Cloudflare Workers AI

developers.cloudflare.com

Workers AI は Cloudflare Workers から各種 AI モデルを呼び出すことができるサービスです。モデルは結構色々あって、Text Embedding に使える @cf/baai/bge-base-en-v1.5 というモデルがあり、今回はこれを使って記事の内容をベクトル化しています。

Models

developers.cloudflare.com

wrangler.jsonc に設定を行い、次のようなコードでベクトルを生成できます：

{
  "ai": {
    "binding": "AI"
  }
}

const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
    text: article.content,
});
const embedding = response.data[0]; // number[]

@cf/baai/bge-base-en-v1.5 は英語用のモデルで、現時点では英語のモデルしか利用できませんが、今回は Cloudflare Workers で完結させたかったため、精度には目をつぶることにしました。記事が少ないのでなんとも言えないですが、それっぽい結果にはなってる気がします。ここは好きなモデルを使えるので、 Workers AI ではなく、コードを書いて Open AI のモデルを使うとかでもよいです。

Vectorize でのベクトルデータの管理

Cloudflare Vectorize

developers.cloudflare.com

Cloudflare Workers から触れるベクトルデータベースで、手軽にベクトルの保存や検索を行うことができます。

使用するために準備として wrangler からデータベースを作成します：

bun wrangler vectorize create related-articles-index --preset="@cf/baai/bge-base-en-v1.5"

Workers AI を使用する場合モデルに合わせてプリセットを指定することで、互換性のある設定が自動的に行われます。そうでない場合は、 --dimensions と --metric を指定して作成します。

出力された設定情報を wrangler.jsonc に追加します：

{
  "vectorize": [
    {
      "binding": "VECTORIZE",
      "index_name": "related-articles-index"
    }
  ],
}

データの挿入

検索対象にしたい記事をベクトル化してデータベースに登録します。 Worker AI で取得した embedding を、以下のように upsert で保存します：

await env.VECTORIZE.upsert([{
    id: article.id, // どこからでも作れるように、記事の URL に対応した形式にしている
    values: embedding,
    metadata: {
        url: article.url,
        title: article.title,
        emoji: article.emoji,
        content: article.content
    },
}]);

これを適当な Web API としてまとめ、 GitHub Actions で SSG するときに全記事分リクエストを投げています。現状は記事数が少ないため、毎回全データを上書きする形で実装しています。

ローカル開発環境

注意点としてローカルでの開発時は、Workers AI と Vectorize を使用するために --remote オプションを付けて起動する必要があります：

$ wrangler dev --remote

Dev Container での wrangler dev で dev-server に繋がらない場合の対処

Sun, 02 Feb 2025 14:40:03 GMT

wrangler dev コマンドは Cloudflare での動作を想定した dev-server を実行できるコマンドですが、Dev Container 内でこれを実行した場合に発行される URL にアクセスしても、レスポンスが一切返ってこない状態になりました。コンテナの実行には OrbStack を利用しています。解決法を探してみたところ次のような Issue がありました。

🐛 BUG: I can't access the development server I launched with wrangler dev in DevContainer · Issue #6587 · cloudflare/workers-sdk

Which Cloudflare product(s) does this pertain to? Wrangler What version(s) of the tool(s) are you using? 3.72.3 What version of Node are you using? v22.7.0 What operating system and version are you...

github.com

どうやら --ip 127.0.0.1 を加えて起動するとうまくいくことがあるようです。

$ npx wrangler dev --ip 127.0.0.1

今回自分はこれで動作しました。ただし、Dev Container でないローカル環境などではこれでは実行できなくなるので、注意が必要です。

Cloudflare Workers の Static Assets と Frameworks を試す

Sun, 02 Feb 2025 00:00:00 GMT

これを書いている時点ではβ版となっていますが、 Cloudflare Workers に Static Assets と Frameworks という機能が追加されていて、これまで Pages 側の機能だった静的ファイルの配信が Workers に統合されつつあるようです。これを利用すると Workers 単体で SSG なコンテンツを配信したり、 Next.js や Astro のサーバーサイド機能をうまく使うことが出来るようなので、これはそのサンプルを触ってみたログです。

Static Assets

Create full-stack applications deployed to Cloudflare Workers.

developers.cloudflare.com

Framework guides

Create full-stack applications deployed to Cloudflare Workers.

developers.cloudflare.com

チュートリアルをなぞって少し手を加えた程度のものですが、コードは以下にあります。

GitHub - yaakaito/workers-static-assets-example

Contribute to yaakaito/workers-static-assets-example development by creating an account on GitHub.

github.com

基本的な機能

特にフレームワークを利用しないプレーンなアプリは Deploy a full-stack application に従って以下のコマンドでこれを試すことができます。デフォルトが Vite なので、個人的にはもっとシンプルな構成であると嬉しかったです。

$ npm create cloudflare@latest -- my-dynamic-site --experimental

生成されたものをみると、Wrangler の設定ファイルである wrangler.json もしくは wrangler.toml に assets フィールドが追加されていて、これで設定を行うようです。

Configuration and Bindings

Details on how to configure Workers static assets and its binding.

developers.cloudflare.com

JSON の場合は次のようにディレクトリを指定すると、そのディレクトリ以下のファイルが wrangler deploy でアップロードされます。

{
  "main": "src/index.ts",
  "assets": {
    "directory": "./public/"
  }
}

ここに該当するファイルがあれば Workers の main よりも先にそれが返され、そうでなければ main に指定したスクリプトに到達するようです。

Next.js + PPR

Next.js

Create an Next.js application and deploy it to Cloudflare Workers with Workers Assets.

developers.cloudflare.com

$ npm create cloudflare@latest my-next-app -- --framework=next --experimental

@opennextjs/cloudflare を利用して、 Workers で動作する形にビルドしているようです。

Index - OpenNext

Open-source Next.js adapters

opennext.js.org

Cloudflare WorkersとNext.jsインテグレーションの問題にOpenNext実装が加わった - laiso

Cloudflareが@opennextjs/cloudflareを発表 2024年9月末に開催された「Builder Day 2024」でNext.jsアプリをCloudflare Workersにデプロイする新たな方法が公開された。この方法は、@opennextjs/cloudflareを使ってビルドする。既存の@cloudflare/next-on-pages方式を置き換える可能性があり、現在は実験的な段階だ。以下に新旧の開発手順のドキュメントがある。新(opennextjs): Next.js | Cloudflare Workers docs 旧(next-on-pages):…

laiso.hatenablog.com

概ねうまく動作しているように見えるのですが、Partial Prerendering が備え付けの preview コマンドだとうまく動作しませんでした。next dev や実際の Workers の環境では問題なく動作しているので、 Wrangler 特有の問題なのかもしれませんが、基本的な開発は next dev だと思うのであまり気にする必要はなさそうです。

他にも現状だとサポートされていない機能がいくつかあって、特に ISR が使えないのが気になります。そのうち対応される気もするので使いたい場合は待つことになります。

Index - OpenNext

Open-source Next.js adapters

opennext.js.org

Astro + Server Islands

Astro

Create an Astro application and deploy it to Cloudflare Workers with Workers Assets.

developers.cloudflare.com

npm create cloudflare@latest my-astro-app -- --framework=astro --experimental

@astrojs/cloudflare を使って動作します。

@astrojs/cloudflare

Learn how to use the @astrojs/cloudflare adapter to deploy your Astro project.

docs.astro.build

Server Islands を試しましたが、問題なく動いているように思えました。個人的に Astro といえば SSG で、 GitHub Pages にデプロイすればいいかくらいの温度感で使っていたので、Workers で Server Islands が使えるのは出来ることが広がりそうだなという感触があります。この記事も Astro で書いたものを GitHub Pages においているのですが、そのうち Workers へ引っ越すかもしれません。

Server islands

Combine high performance static HTML with dynamic server-rendered content.

docs.astro.build

直接今回の話とは関係ないのですが、Dev Container + OrbStack で astro dev で起動したサーバーにブラウザからアクセスができないという問題がありました。コンテナ内からの curl は通る状態です。Codespace や Dev Container でないローカル環境では動作するので、 OrbStack 特有の問題だと思いますが未解決です。Docker Desktop ですが次のような記事がありました。

[mac]devcontainerで立ち上げたローカルサーバーに接続できない（built-in port-forwarding） - Qiita

結論：Docker Desktopのせい。事象 astro で静的サイトを作るため、VSCodeの devcontainer を利用しました。 npx astro dev で起動するとこんなのが出るので「ブラウザーで開く」をクリックしても、ブラウザーはグルグルするも...

qiita.com

雑感

Workers と Pages が徐々に統合されるという流れがあったと思うのですが、 Static Assets でこの流れが一気に進んだように思えます。出来るとわかりつつも、 Cloudflare Workers 上に Web UI をもつアプリケーションを作るのは少し億劫なところがあったのですが、 Static Assets が入るとそれが解決するので、個人開発レベルなら Cloudflare 1 本でも困ることがなくなりそうです。

TypeScript 5.8 の --erasableSyntaxOnly

Tue, 28 Jan 2025 09:21:41 GMT

Node がデフォルトでの TypeScript の実行をサポートしたことに伴って、それを更にサポートするフラグが TypeScript に追加されるようです。

Announcing TypeScript 5.8 Beta - TypeScript

Today we are excited to announce the availability of TypeScript 5.8 Beta. To get started using the beta, you can get it through npm with the following command: npm install -D typescript@beta Let’s take a look at what’s new in TypeScript 5.8! Checked Returns for Conditional and Indexed Access Types Consider an API that presents […]

devblogs.microsoft.com

Tsconfig option to disallow features requiring transformations which are not supported by Node.js' --strip-types · Issue #59601 · microsoft/TypeScript

🔍 Search Terms --strip-types ✅ Viability Checklist This wouldn't be a breaking change in existing TypeScript/JavaScript code This wouldn't change the runtime behavior of existing JavaScript code Th...

github.com

これを利用すると、 enum や namespace といった TS 特有の機能を無効化し、削除可能な型情報のみを扱うことが出来るようになります。Node の TS サポートでは、これらの構文を実行するために別途 --experimental-transform-types フラグが必要でしたが、今回 --erasableSyntaxOnly が導入され、それを利用することで、Node と互換性の高いコードを書けることが期待されているようです。

Temporal が Firefox Nightly で一部利用可能に

Mon, 27 Jan 2025 11:39:03 GMT

長らく使われてきた Date に変わるものとして Temporal が提案されていましたが、その実装が Firefox の Nigthly ビルドに含まれるようになったようです。

JavaScript Temporal is coming

A new way to handle dates and times is being added to JavaScript. Let's take a look at Temporal, what problems it solves, the current state, and what you'll find in the new documentation about it on MDN.

developer.mozilla.org

大きな特徴として、Wall-Clock Time (その地域時間) と Exact Time (UTC) が分離しました。Plain がつくものが Wall-Clock Time で、 Instant が Exact Time です。

>> Temporal.Now.instant().toString()
← "2025-01-27T11:12:04.997Z"
>> Temporal.Now.plainDateTimeISO().toString()
← "2025-01-27T20:12:23.839"

また、期間を表す概念として Duration があります。

>> Temporal.Duration.from({ hours: 1}).toString()
← "PT1H"

これまでライブラリで行っていたような操作も多くのメソッドが追加され、ネイティブでサポートされるようになります。

>> Temporal.PlainDate.from('2025-01-01').since(Temporal.Now.plainDateISO()).toString()
← "-P26D" 
>> Temporal.PlainDateTime.from('2025-01-01').add('P26DT12H').toString()
← "2025-01-27T12:00:00"

Refs

zenn.dev

Popover API と Dialog に関する備忘録

Thu, 23 Jan 2025 00:00:00 GMT

2024 年の Baseline に追加された機能として Popover API があり、またそれに関連するものとして Dialog がすでに実装されている。この 2 つは目的は違うが技術的には似たものになっているので、それぞれの特徴などをまとめる。

動作サンプル: https://yaakaito.github.io/code-sandbox/popover-and-dialog/

前提知識

Top Layer

Top layer (最上位レイヤー) - MDN Web Docs 用語集 | MDN

最上位レイヤーは、ビューポートの幅と高さ全体にわたり、ウェブ文書内に表示される他のすべてのレイヤーの最上位に位置する固有のレイヤーです。これは、ページ上の他のすべてのコンテンツの上に現れるべき要素を含むために、ブラウザーによって作成されます。

developer.mozilla.org

従来のz-indexとは異なる、ブラウザネイティブの最前面レイヤー。PopoverとDialogのモーダルモードは、このTop layerを利用して要素を描画する。入れ子も可能だが、Light Dismiss（要素外クリックでの閉じる）の挙動には注意が必要となる。

利用用途による違い

Popover
- カレンダーのようなフォームでの特殊な入力 UI
- 通知、トースト
- チュートリアル UI
モーダル Dialog
- 利用規約への同意のようなそれ以外を操作できないような UI
- 削除のような重要な確認操作
非モーダル Dialog
- Cookie の利用許可のような、ユーザーに同意を求めるが、コンテンツは操作できる UI
- プライベート URL で共有を行うようなコンテンツでの、共有に関する警告の UI

Popover

ポップオーバー API - Web API | MDN

ポップオーバー API は、他のページコンテンツの上に表示するポップオーバーコンテンツを表示するための、標準的な、一貫性のある、柔軟な仕組みを開発者に提供します。ポップオーバーコンテンツは、HTML 属性を用いて宣言的に、または JavaScript を用いて制御することができます。

developer.mozilla.org

Popover は属性で、任意の要素を Top layer へ配置することができる。ダイアログやモーダルではないので、アクセシビリティといった視点で意味は持たず、基本的には背景の要素に操作が貫通する。

<button popovertarget="mypopover">toggle popover</button>
<div id="mypopover" popover="auto|manual|hint">Popover content</div>

popover 属性には現状 3 つの値を設定することができ、これによって Light Dismiss や表示方法をコントロールする。

auto: デフォルト値で、Light Dismiss が有効になる
manual: Light Dismiss が無効になり、閉じるための動作を実装する必要がある
hint: 「hint」は Chrome 133 から導入された（される予定の）機能で、この値が設定されている Popover は同時に1つしか表示されない

JS からもコントロール可能だが、必ず属性に popover が付与されている必要がある。

popover.showPopover()
popover.hidePopover()

Dialog

<dialog>: ダイアログ要素 - HTML | MDN

<dialog> は HTML の要素で、モーダルまたは非モーダルダイアログボックスや、それ以外の消すことができるアラート、インスペクター、サブウィンドウなどのような対話的コンポーネントを表します。

developer.mozilla.org

Dialog はユーザーに操作を求めるための役割（role=dialog）を持つ。モーダル/非モーダルの2つのモードがあり、特にモーダルモードではTop layerへの表示と背景操作のロックを行う。JS での制御が想定されていて、showModal() を利用することでモーダルダイアログが、show() を利用することで非モーダルダイアログが表示される。

<dialog id="dialog">
    <h1>Dialog</h1>
    <p>This is a dialog.</p>
    <button>Close</button>
</dialog>
<script>
    const dialog = document.getElementById('dialog');
    dialog.showModal();
</script>

モーダルの場合、次の機能がブラウザネイティブで提供される。これによって、これまでの実装よりもアクセシビリティや UX の向上が期待できる。

inert による背景 UI のロック
- HTML inert グローバル属性 - HTML | MDN
  inert グローバル属性は論理属性で、要素とそのフラットツリーの子孫すべてが「不活性」になることを示す論理属性です。 showModal() に対応するモーダルダイアログ (<dialog>) は、不活性状態から脱します。つまり、先祖から不活性を受け継ぐことはなく、自身に inert 属性を明示的に設定した場合にのみ不活性になります。
  developer.mozilla.org
- .showModal() で表示された Dialog は、Top Layer でない要素が inert となる
:backdrop による背景の表示
- ::backdrop - CSS | MDN
  ::backdrop は CSS の擬似要素で、何らかの要素が全画面モード（最上位レイヤー）で表示される直下に直接表示されるビューポートの寸法のボックスです。
  developer.mozilla.org
- Top layer と背景コンテンツの間に表示される領域で、モーダルダイアログではデフォルトで半透明の背景が表示されており、ユーザーの操作を受け付けないことを表現している
ESC での閉じるのサポート
- Light Dismiss ではない
フォーカスの管理
- モーダルダイアログが表示された際に、その中の要素にフォーカスが移動する
- ダイアログが閉じられた際に、直前のフォーカス位置に戻る

Anchor Positioning

CSS アンカー位置指定の使用 - CSS | MDN

CSS アンカー位置指定モジュールは、要素を結びつけるための機能を定義します。要素は、アンカー要素とアンカー位置指定要素として定義できます。アンカー位置指定要素は、アンカー要素に束縛することができます。アンカー位置決めされた要素は、そのサイズと位置を、結合されたアンカー要素のサイズと位置に相対的に設定することができます。

developer.mozilla.org

特定要素を基準とした配置をサポート。Top layer要素でも有効で、Popoverと組み合わせて使用できる。

<style>
   #anchorPopoverTrigger {
        anchor-name: --anchor-target;
   }
   #anchorPopover  {
        position-anchor: --anchor-target;
        position-area: bottom span-right;
        position-try-fallbacks: flip-inline, flip-inline flip-block;
        margin: 0;
        width: 300px;
   }
</style>
<button id="anchorPopoverTrigger" popovertarget="anchorPopoverLeft">toggle anchor popover</button>
<div id="anchorPopover" popover>
    Anchor Popover Left
</div>

position-area による配置指定が基本となりそうだが、top や left などを使用した直接的な位置指定も可能。

CSS アンカー位置指定の使用 - CSS | MDN

developer.mozilla.org

fallback を設定することができ、画面に収まらない場合の挙動を調整することが出来る。

position-try-fallbacks - CSS | MDN

The position-try-fallbacks CSS property enables you to specify a list of one or more alternative position try fallback options for anchor-positioned elements to be placed relative to their associated anchor elements. When the element would otherwise overflow its inset-modified containing block, the browser will try placing the positioned element in these different fallback positions, in the order provided, until it finds a value that stops it from overflowing its container or the viewport.

developer.mozilla.org

Close Watcher

CloseWatcher - Web APIs | MDN

The CloseWatcher interface allows a custom UI component with open and close semantics to respond to device-specific close actions in the same way as a built-in component.

developer.mozilla.org

ユーザーが閉じようとした動作を検知できる API で、具体的には ESC や戻るを押したタイミングが検知できる。popover=manual や非モーダルダイアログには ESC での閉じる機能がないので、対応する必要が出てきたときに有効。

let closeWatcher = null
popoverTrigger.addEventListener('click', () => {
    if (closeWatcher) {
        closeWatcher.destroy()
    }
    closeWatcher = new CloseWatcher()
    closeWatcher.onclose = () => {
        popover.hidePopover()
    }
    popover.showPopover()
})

Refs

#Tags | blog.jxck.io

blog.jxck.io

zenn.dev

UI を閉じる動作を処理する CloseWatcher API

CloseWatcher API は UI を閉じる動作を処理するための API です。キーボードの `Esc` キー、Android の戻るボタンなどのデバイス固有のメカニズムによって閉じるイベントを提供します。

azukiazusa.dev

Node がデフォルトで TypeScript をサポートするようです

Sat, 28 Dec 2024 09:58:23 GMT

--experimental-strip-types を使うことで Node で TS を実行することができていましたが、フラグが不要になるようです。

module: unflag --experimental-strip-types by marco-ippolito · Pull Request #56350 · nodejs/node

It&#39;s time to enable it by default to catch some more bugs, currently there are no open issues. I think it&#39;s a semver minor change. Fixes: nodejs/typescript#17 @nodejs/tsc for visibility Not...

github.com

Node.js Now Supports TypeScript By Default

TypeScript is coming to Node 23. Let's break down what that means.

www.totaltypescript.com

フラグが削除されるだけなので allowImportingTsExtensions を設定したりといったことは引き続き必要です。ただ、次期 TS バージョンにおいてこのあたりも整理される予定とのこと。

namespace や enum といった TS の機能を利用するには引き続き --experimental-transform-types が必要です。

--experimental-strip-types と Node 組み込みランナーで TypeScript をテストをする

Mon, 16 Dec 2024 19:08:14 GMT

前回の続きのようなもので、Node 22.6 で --experimental-strip-types が入ったので swc-node を使う必要がなくなりました。次のようなコマンドで、 Node の組み込みテストランナーを使って TypeScript のテストが実行できます。

$ node --experimental-strip-types --watch --test 'src/**/*.test.ts'

ただしすんなり動くわけではなく、やはりモジュールの解決周りで調整が必要になります。ここに詳しく解説するスペースはないので、詳しく知りたい方はリンクを参照してください。

前回はコード上では .js を省略しない import とし、bundler 側で辻褄を合わせていました。--experimental-strip-types の場合は現状では .(m)ts が省略できなくなるので、コード上の import を .ts に書き直しました。このままだとエディタ上でエラーとなってしまうため、 tsconfig.json で allowImportingTsExtensions と noEmit を立てます。

{
    "compilerOptions": {
        "allowImportingTsExtensions": true,
        "noEmit": true
    }
}

また、namespace や enum のような、型の表現以外の TypeScript のコードを実行するには別途 --experimental-transform-types が必要です。今回は必要ないコードしかなかったので指定しませんでした。

Refs

Node.jsでTypeScriptのコードを実行できるようになるかも | hiroppy's site

Node.jsでTypeScriptのコードを実行できるような機能が提案されました

hiroppy.me

zenn.dev

Node.js — Node.js 22.6.0 (Current)

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

--noCheck オプションで tsc でも型チェックをスキップできるように

Mon, 16 Dec 2024 18:11:48 GMT

TypeScript 5.6 から --noCheck オプションが追加され、これまで必ず行われていた型チェックが tsc 単体でもスキップできるようになりました。

$ tsc --noCheck

swc などが主流で、Node も単体で TS の実行をサポートしようとしていたりする中で、特別用途があるのかというと… という感じです。

Refs

Announcing TypeScript 5.6 - TypeScript

Today we’re excited to announce the release of TypeScript 5.6! If you’re not familiar with TypeScript, it’s a language that builds on top of JavaScript by adding syntax for types. Types describe the shapes we expect of our variables, parameters, and functions, and the TypeScript type-checker can help catch issues like typos, missing properties, and […]

devblogs.microsoft.com

Declarative Shadow DOM

Sun, 03 Nov 2024 18:41:35 GMT

Baseline 2024 で追加された、これまで JavaScript からしか生成できなかった Shadow DOM を HTML で定義できるようになる機能です。これによって、Web Components をサーバーサイドでのレンダリングに対応させることができます。

次のような HTML として記述することで Shadow DOM が生成されます。(動作サンプル)

<my-custom-element data-count="12345">
    <template shadowrootmode="open">
        <style>
            * {
                margin: 0;
                padding: 0;
            }
            .container {
                display: flex;
                gap: 8px;
            }
            .counter {
                font-weight: bold;
            }
            .increment, .decrement {
                width: 20px;
                cursor: pointer;
            }
        </style>
        <div class="container">
        <p class="counter">12345</p>
        <button class="increment">+</button>
        <button class="decrement">-</button>
        </div>
    </template>
</my-custom-element>

同名で customElements.define された HTMLElement があれば、自動的にアップデートされ、 constructor や connectedCallback で Hydration を行うことができます。

class MyCustomElement extends HTMLElement {
    connectedCallback() {
        let count = parseInt(this.getAttribute('data-count'))
        this.shadowRoot.querySelector('.increment').addEventListener('click', () => {
            this.shadowRoot.querySelector('.counter').textContent = String(++count)
        })
        this.shadowRoot.querySelector('.decrement').addEventListener('click', () => {
            this.shadowRoot.querySelector('.counter').textContent = String(--count)
        })
    }
}
customElements.define("my-custom-element", MyCustomElement);

Declarative Shadow DOM の形で JavaScript から要素を追加する場合、 $el.innerHTML = htmlString ではセキュリティ上の理由から実行が行われず、代わりに setHTMLUnsafe や parseHTMLUnsafe を利用する必要があります。

Refs

宣言型の Shadow DOM  |  web.dev

宣言型 Shadow DOM は、Shadow DOM を HTML で直接実装して使用する新しい方法です。

web.dev

HTML だけで Shadow DOM を構築するための宣言型 Shadow DOM

宣言型 Shadow DOM は `<template>` 要素を使用して Shadow DOM を構築する方法です。宣言型 Shadow DOM を使用することで、従来の JavaScript を使用した Shadow DOM の構築方法と比較して、サーバーサイドレンダリング（SSR）に対応しているため、パフォーマンスの向上や SEO 対策に期待されます。

azukiazusa.dev

zenn.dev

TypeScript 5.6 の Disallowed Nullish and Truthy Checks と ESLint no-constant-binary-expression

Thu, 10 Oct 2024 07:52:06 GMT

TypeScript 5.6 から、常に真または偽になるような意図していない条件式や、Null 合体演算子 (??) を誤って使用している場合にエラーとなるようになりました。

Announcing TypeScript 5.6 - TypeScript

devblogs.microsoft.com

公式のコードを引用すると次のような場合にエラーが発生するようなります。

if (/0x[0-9a-f]/) { } // error: This kind of expression is always truthy.
if (x => 0) { } // error: This kind of expression is always truthy.

特に Null 合体演算子の誤用は、コードが直感に反していることもあり大きな恩恵を得ることが出来そうです。例えば次のコードは options.max が未定義の際に value < 100 と扱われるように思えますが実際にはそうではありません。

return value < options.max ?? 100;
// error: Right operand of ?? is unreachable because the left operand is never nullish.

これは実際には (value < options.max) ?? 100 と扱われます。実数にした適当なコードを実行してみると、結果が予想と異なっていることがわかります。

10 < {}.max ?? 100
// > false

また、この新しい機能は ESLint の no-constant-binary-expression ルールが元になっているようです。

no-unused-binary-expressions: From code review nit to ecosystem improvements - ESLint - Pluggable JavaScript Linter

A pluggable and configurable linter tool for identifying and reporting on patterns in JavaScript. Maintain your code quality with ease.

eslint.org

Speculation Rules API を使ったページの事前レンダリング

Mon, 19 Aug 2024 14:53:42 GMT

rel="prerender" を利用したページの事前読み込みに変わる次世代の API として、 Speculation Rules API というものが Chrome に導入されました。

Chrome でページを事前レンダリングしてページナビゲーションを即時に行う  |  Web Platform  |  Chrome for Developers

Chrome チームでは、ユーザーがアクセスする可能性の高い今後のページを完全に事前レンダリングする機能の開発に取り組んできました。

developer.chrome.com

<script> で比較的簡単な記述をするだけでページの事前準備をすることができ、前回の View Transition API と組み合わせるとネイティブアプリのような滑らかなページ遷移を実現することが出来るようです。View Transition API の例を元にすると、次のようなコードで遷移先の内容を読み込んでおくことができます。

<!DOCTYPE html>
<html lang="en">
  <!-- 略 -->
  <body>
    <nav>
      <ul>
        <li id="navHome">
          <a href="./index.html">🏠 Home</a>
        </li>
        <li id="navBlog">
          <a href="./blog.html">🖊 Blog</a>
        </li>
        <li id="navAbout">
          <a href="./about.html">🐴 About</a>
        </li>
      </ul>
    </nav>
    <div id="mark"></div>
    <script type="speculationrules">
      {
        "prerender": [
          {
            "urls": ["about.html", "blog.html"]
          }
        ]
      }
    </script>
  </body>
</html>

実際の動作を比べてみると、View Transition API のみでは一度遷移し読み込みが完了するまで少し待ってからアニメーションが動作するのに対して、Speculation Rules API も足すことでクリック直後に素早くアニメーションと遷移が動作するようになります。

yaakaito.github.io

DevTool で動作確認を行う場合、 Application > Background Services > Speculative loads から動作を確認できます。

また、JavaScript から動的にルールを生成することも可能です。

Chrome でページを事前レンダリングしてページナビゲーションを即時に行う  |  Web Platform  |  Chrome for Developers

Chrome チームでは、ユーザーがアクセスする可能性の高い今後のページを完全に事前レンダリングする機能の開発に取り組んできました。

developer.chrome.com

View Transition API を使った MPA でのページ間アニメーション

Tue, 23 Jul 2024 14:40:10 GMT

Chrome 126 で SPA でない通常のページ遷移の際にも間を補完するアニメーションを実装することが可能になりました。

Novità di Chrome 126  |  Blog  |  Chrome for Developers

È in corso l'implementazione di Chrome 126. Grazie al supporto delle transizioni tra documenti nell'API ViewTransiziones, l'API CloseWatcher ha riattivato l'utilizzo, ha generato voci di trigger per l'API Gamepad e non solo, ma c'è molto altro e molto altro ancora. Adriana Jara ha tutti i dettagli sulle novità per gli sviluppatori in Chrome 126.

developer.chrome.com

View Transition API によるスムーズな遷移  |  View Transitions  |  Chrome for Developers

View Transition API を使用すると、ウェブサイトのビュー間の遷移を追加できます。

developer.chrome.com

次の CSS を遷移元と遷移先で設定しておくことで、デフォルトではフェードイン・アウトなアニメーションが適用されるようになります。

@view-transition {
  navigation: auto;
}

例としてナビゲーションにマーカーが付くようなページを用意しました。

yaakaito.github.io

これは CSS Anchor Positioning API を利用して実装していて、それぞれのページでは position-anchor にそのページのものを指定するだけでページ遷移時にアニメーションが適用されます。

CSS アンカーポジショニング API のご紹介  |  Blog  |  Chrome for Developers

新しい Anchor Positioning API を使用して、要素を互いに相対的に配置します。

developer.chrome.com

  <body>
    <nav>
        <ul>
            <li id="navHome">
                <a href="./index.html">🏠 Home</a>
            </li>
            <li id="navBlog">
                <a href="./blog.html">🖊 Blog</a>
            </li>
            <li id="navAbout">
                <a href="./about.html">🐴 About</a>
            </li>
        </ul>
    </nav>
    <div id="mark"></div>
  </body>

@view-transition {
  navigation: auto;
}
#navHome {
  anchor-name: --anchor-home;
}
#navBlog {
  anchor-name: --anchor-blog;
}
#navAbout {
  anchor-name: --anchor-about;
}
#mark {
  position: absolute;
  position-anchor: --anchor-home;
  background: black;
  left: anchor(left);
  top: anchor(top);
  width: 4px;
  height: 32px;
  view-transition-name: mark;
}

#mark {
    position-anchor: --anchor-home;
}

React 19 の use で Suspense に対応したコンポーネントを作る

Tue, 04 Jun 2024 19:27:05 GMT

React 19 では use が導入され、これを利用すると <Suspense> に対応したコンポーネントの作成が容易になります。

ja.react.dev

- This feature is available in the latest Canary version of React

ja.react.dev

Promise を use を経由して利用すると、それが完了していない場合に例外が投げられるので、これがそのまま Suspense の実装として使えます。公式にも書かれていますが、これを try-catch すると例外として拾ってしまうので動作しなくなります。

import {use} from 'react';

function ChildComponet() {
  const data = use(aPromise)
  return <div>{data}
}

function App() {
  return (
    <Suspense fallback={<p>loading</p>}>
      <ChildComponent />
    </Suspense>
  )
}

通常の Hooks と異なり、 if を絡めて早期 Return などを書くことも可能です。

:has() でリストが空のときにセクションごと消す

Sun, 02 Jun 2024 20:14:07 GMT

:has() が 2023 年末にすべてのブラウザでサポートされて、現実的に利用できるようになりました。

:has() - CSS | MDN

:has() は CSS の擬似クラス関数で、引数として渡される相対セレクターのいずれかが、その要素から辿ってアンカーとして少なくとも一つの要素と一致する場合に、その要素を表します。この擬似クラスは、相対セレクターリストを引数として取ることで、参照している要素に関して親要素や前の兄弟要素を選択する方法を提供します。

developer.mozilla.org

朗報！ CSSの:has()疑似クラスがすべてのブラウザにサポートされました、:has()疑似クラスの便利な使い方のまとめ

CSSの:has()疑似クラスは便利そうだけどブラウザのサポートがまだ、と見送っていた人に朗報です。12/19にリリースされたFirefox 121（リリース情報）でサポートされ、これで:has()疑

coliss.com

「渡したセレクターにマッチする子要素を持つ親要素であるか」を判定できるので、例えばリストが空のときにセクションごと消すことができます。

<style>
section:has(ul:empty) {
  display: none;
}
</style>
<section class="section">
  <h1>section1</h1>
  <ul>
    <li>item1</li>
    <li>item2</li>
  </ul>
</section>
<section class="section">
  <h1>section2</h1>
  <ul>
  </ul>
</section>

CLI から VSCode の拡張を入れる

Sun, 02 Jun 2024 20:13:54 GMT

--install-extension というコマンドがあり、これを使うと CLI から拡張機能をインストールできます。プロジェクトに直接関係しないが devcontainer に入っていてほしい、みたいなものに個人の設定で使うと便利そうです。

code --install-extension mhutchie.git-graph
code --install-extension eamodio.gitlens

Node 組み込みテストランナーと swc で TypeScript をテストする

Sun, 02 Jun 2024 20:13:39 GMT

Node 18 から実験的に導入された組み込みのテストランナーがありますが、これが 21 で対象を glob 指定できるようになりました。

Node.js — Node.js 18 is now available!

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

Node.js — Node.js 21 is now available!

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

swc-node と組み合わせると、それなりに使えそうなテストランナーになりそうです。

GitHub - swc-project/swc-node: Faster ts-node without typecheck

Faster ts-node without typecheck. Contribute to swc-project/swc-node development by creating an account on GitHub.

github.com

これらを用意した状態で次のコマンドにすると、 TS をトランスパイルしつつ watch モードで動くテストランナーが作れます。

$ node --import @swc-node/register/esm-register --watch --test 'src/**/*.test.ts'

NOTE

webpack などのバンドラーを使って ESM で記述している場合、Node の ESM と共存できるようにする必要があります。自分は import を *.js で行うようにし、 extentionAlias で import xxx from './xxx.js' を .ts としても解決できるようにしました。 https://webpack.js.org/configuration/resolve/#resolveextensionalias

@mozilla/readability を使った HTML からの本文抽出

Sun, 02 Jun 2024 20:13:24 GMT

@mozilla/readability を使うと簡単に本文を抽出することができます。これは Firefox のリーダービューで使われているもののようです。

GitHub - mozilla/readability: A standalone version of the readability lib

A standalone version of the readability lib. Contribute to mozilla/readability development by creating an account on GitHub.

github.com

ウェブページをリーダービューでまとめて読む | Firefox ヘルプ

Firefox のリーダービューは、ウェブページからボタンや広告などの余計なものを削除し、記事本文を画面で読みやすくする表示モードです。

support.mozilla.org

今回はこの結果を Claude3 に投げたかったので、DOMPurify を組み合わせて最小限文章がわかりそうな DOM として取り出しています。

GitHub - cure53/DOMPurify: DOMPurify - a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. DOMPurify works with a secure default, but offers a lot of configurability and hooks. Demo:

DOMPurify - a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. DOMPurify works with a secure default, but offers a lot of configurability and hooks. Demo: - cure53/DOMPurify

github.com

import { Readability } from '@mozilla/readability';
import { JSDOM } from 'jsdom';
import createDOMPurify from 'dompurify';

export const getReadability = async (url: string) => {
    const content = await fetch(url).then(res => res.text());
    const reader = new Readability(new JSDOM(content, {
        url
    }).window.document);
    const readability = (reader.parse() ?? { content: '' });
    return createDOMPurify(new JSDOM('').window).sanitize(readability.content, {
        ALLOWED_TAGS: [
            'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
            'blockquote', 'code', 'pre',
            'p', 'br', 'hr',
            'a', 'img', 'table', 'thead', 'tbody', 'tr', 'th', 'td',
            'ul', 'ol', 'li',
            'dl', 'dt', 'dd',
        ],
        ALLOWED_ATTR: ['href', 'src', 'title', 'alt'],
    });
}

React 19 Actions

Sun, 02 Jun 2024 20:13:05 GMT

React 19 では、データ更新とそれに伴う一連の流れをうまく扱う方法として Actions が導入されるようです。例えば、これまでフォームの送信中の状態を次のように扱うことがありましたが、これが React の機能として標準化されます。

const [isPending, setIsPending] = useState(false);
const submit = () => {
  setIsPending(true);
  await foo();
  setIsPending(false);
}
return (
      <form>
        <button click={submit} disable={isPending}>foo</button>
      </form>
    )

新しく導入される Actions の一つである useActionState を利用して書くと次のように書けます。

const [error, submitAction, isPending] = useActionState(
  async () => {
    const error = await foo();
    if (error) { return error; }
    return null;
  }
)
return (
      <form action={submitAction}>
        <button type="submit" disable={isPending}>foo</button>
      </form>
    )

Hook に渡した関数は実質的に submitAction の内容になっていて、isPending はその関数の実行状態に合わせて値が変化します。これによって最初のコードと同等に isPending を使って UI の状態を変更できる、ということのようです。

useFormStatus

これに組み合わせて使えるものとして useFormStatus という親の form の実行状態を取得することが出来る Hook もあります、これは react-dom から提供されるものです。例えばボタンコンポーネントを作るときにその状態を外から Props として渡すことがあると思いますが、 Actions を使った form の中ではこれを簡略化することが出来ます。

function FooSubmit() {
  const { pending } = useFormStatus();
  <button type="submit" disable={pending}>foo</button>
}

function FooForm() {
  const [error, submitAction, isPending] = useActionState(
    async () => {
      const error = await foo();
      if (error) { return error; }
      return null;
    }
  )
  return (
        <form action={submitAction}>
          <FooSubmit />
        </form>
      )
}

これが useActionState の例と同じ動作になるようです。

useOptimistic

Actions が失敗したときに巻き戻される useState のようなものです。次にコードで await foo() が失敗すると、 value が currentValue に戻ります。

const [value, setValue] = useOptimistic('currentValue')
const [error, submitAction, isPending] = useActionState(
  async () => {
    setValue('newValue')
    const error = await foo();
    if (error) { return error; }
    return null;
  }
)>

ユーザー名を変更したいが、重複チェックに時間がかかるような場合に、結果の予定を先に UI に反映しておくような場合にその実装が標準化できるようです。

react.dev

- This feature is available in the latest Canary version of React

react.dev

node 22 の標準 glob を利用する

Sun, 02 Jun 2024 20:07:55 GMT

Node 22 では実験的な機能として glob と globSync が導入されました。

Node.js — Node.js 22 is now available!

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

nodejs.org

これまで glob パッケージを利用していた場合、次のように置き換えることが出来ます。

Just a moment...

www.npmjs.com

- const glob = require('glob');
+ const { glob, globSync} = require('fs');

  glob('*', (error, matches) => {});
- const matches = glob.sync('*');
+ const matches = globSync('*');

個人開発を Codespaces と DevContainer へ移行

Sat, 06 May 2023 00:00:00 GMT

Codespaces が利用できるようになってから、ちょっとした開発は Codespaces を行っていたのですが、最近は個人の開発はすべて Codespaces で十分だと思えてきたので完全に移行しようと思いました。ただ、基本的には無料枠でやっているので¹、ある程度腰を据えて開発していると枠が足りなくなるのと、Chrome 拡張の開発は毎回成果物のダウンロードが必要だったりで不便なところは少しあるので、それを埋めるために一部で Dev Container を使って、手元のマシン内で開発可能な環境を整えることにしました。

これは、その準備をしたときの作業ログと未来の自分に向けたメモです。ある程度 Codespaces を触ったことがあるという前提で書かれています。

開発用コンテナと Dockfile について

Codespaces と Dev Container で使用するコンテナに関する設定を区別する必要なく、同じものが使えます。 Docker Desktop に相当するものがインストールされていれば、VSCode に Dev Containers のプラグインを入れればそのまま利用可能です。

Dev Containers - Visual Studio Marketplace

Extension for Visual Studio Code - Open any folder or repository inside a Docker container and take advantage of Visual Studio Code's full feature set.

marketplace.visualstudio.com

ローカルで開発するときはコードを適当な場所に clone して「Open in container」から開きます。コマンドパレットからも開き直せます、その場合は Reopen ~ になります。

Clone Repository in Container

コードの clone をコンテナの中で行うという方法もあるようです。これを利用すると Codespace とほとんど同じ感覚で使えるようです。

【vscode】devcontainerのClone in container volumeがよいという話

今回は、 vscode で devcontainer を使った開発環境について、「Clone repository in container volume」を使うとうれしい点を取り上げます。

weseek.co.jp

Create a Dev Container

Create a development container using Visual Studio Code Remote Development

code.visualstudio.com

ただ、何回試してみたのですが、shallow clone になってしまってだるいのと、成果物がコンテナ内に入ってしまうので取り出すのがめんどくさい、という理由があって使っていません。

OrbStack

個人の MBA では Docker Desktop の代わりに OrbStack を試しています。

OrbStack · Fast, light, simple Docker & Linux

Say goodbye to slow, clunky containers and VMs. The fast, light, and easy way to run containers and Linux. Develop at lightspeed with our Docker Desktop alternative.

orbstack.dev

zenn.dev

いまのところ特に問題なく Docker Desktop の代わりとして使えています。

Dotfiles について

ここ数年は fish を使っていたのですが、devcontainers のものにはデフォルトでは入っていないので、これを機に zsh に戻してみることにしました。これまで Codespaces を使うときは不便を感じつつも特にカスタマイズをしていなかったので、今回ちゃんと設定を整えてみることにしました。

GitHub - yaakaito/env

Contribute to yaakaito/env development by creating an account on GitHub.

github.com

開発に使う devcontainer をある程度テンプレ化しておきたかったので² dotfiles ではなくて env という名前にしてみました。

Codepsaces の場合は、GitHub の設定から dotfiles のリポジトリを指定することで、Codespaces が起動するときに dotfiles の内容がコンテナにコピーされ、setup.sh が実行されます。

アカウントGitHub Codespaces のカスタマイズ

docs.github.com

Dev Container の場合は、VSCode の設定から GitHub にある dotfiles のリポジトリを指定ことができます。これをすると Codespaces と同等の挙動になります。

{
  "dotfiles.repository": "yaakaito/env",
  "dotfiles.targetPath": "~/.env",
}

zsh のカスタマイズ

とはいえ欲しい物が fish っぽく動いてほしいくらいだったので、次の記事を参考に zsh-autosuggestions と zsh-syntaxhighlight を入れて、fish ライクに、peco で ctrl-r に履歴検索、ctrl-s でディレクトリ移動をバインドしています。

Setup guide for ZSH in GitHub codespaces

Setup ZSH This post will guide you through to set up starship along with zsh suggestions...

dev.to

zenn.dev

pecoを使ったらターミナルの操作が劇的に効率化できた話 - Qiita

はじめに pecoが最強。便利すぎてヤバイよって話です。ターミナルの操作を限りなく高速化したいみなさんに本記事を捧げます。peco童貞の方にとっては、控えめに言っても人生が変わることになる1記事になるでしょう。自信作です。駆け出しエンジニアだった昔の自分に会ったら、...

qiita.com

他には pnpm などの補完がほしいところですが、これは使うコンテナによって必要なものが違うので、Dockerfile の方で有効にしています。例えば pnpm の場合は以下のような感じです。

Command line tab-completion

pnpm.io

USER vscode
RUN corepack prepare pnpm@8.2.0 --activate
RUN pnpm install-completion zsh

Copilot や VSCode の拡張機能について

これまではあまり意識せずに Copilot を Codespaces にインストールして使っていたのですが、これを設定している途中で、コンテナ内で開発する際に Copilot が有効にならないことがあることに気づきました。これは Codespaces に限らず、Dev Container でも同じでした。他にもいくつかの拡張機能が動作しないことがあったのですが、これは container.json に設定を追加することで解決しました。

GitHub Codespaces でのGitHub Copilotの使用

docs.github.com

Development Container Specification

The purpose of the Development Container Specification is to provide a way to enrich containers with the content and metadata necessary to enable development...

containers.dev

customizations.vscode.extensions フィールドを設定することで、コンテナで有効にする VSCode の拡張機能を指定することができるようです。これを使って Copilot や必要な拡張を有効にすることにしました。

{
    "build": { "dockerfile": "Dockerfile" },
    "customizations": {
        "vscode": {
            "extensions": [
                "github.copilot",
                "astro-build.astro-vscode" // 例えば Astro を使う場合
            ]
        }
    }
}

今回やらなかったがやりたいこと

Codespaces や Dev Container を使った開発では、シェルの history が残らないため、永続化したい場合は別途手段を用意する必要があるようです。

zenn.dev

history が永続化できるとそもそも不要かもしれませんが、cheat を使ったスニペットを env リポジトリに含めて置けると便利そうです。

GitHub - cheat/cheat: cheat allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.

cheat allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind *nix system administrators of options for commands that they use frequently, but not ...

github.com

2023-05-14 追記

しばらく触っていなかったリポジトリを同じ要領で触ってみたら、DevContainer 側で VSCode の Extention のインストールが全く進まずに困っていたのですが、Dockerfile が原因でした。かなり前に公式を参考に devcontainer.json と Dockerfile を作った際に、その Dockerfile はこんな感じに定義されていて、

ARG VARIANT=bullseye
FROM --platform=linux/amd64 mcr.microsoft.com/vscode/devcontainers/base:0-${VARIANT}

linux/amd64 を指定していると M2 Mac 上のコンテナに Extention がインストールできなくなるようでした。platform は指定しなければ自動で選択してくれるので、

ARG VARIANT=bullseye
FROM mcr.microsoft.com/vscode/devcontainers/base:0-${VARIANT}

に変更して無事動くようになりました。当時参考にしたドキュメントが見つからなかったんですが、現在のものは platform を指定していないので問題なさそうです。

開発コンテナーの概要

docs.github.com

そもそもトレンドとしては Dockerfile は使わず、devcontainer.json だけで完結するのがよいようにも思います。

Footnotes

追加することに抵抗があるわけではないので、理由がなければ Codespaces を継続してます。 ↩
テンプレートリポジトリはリポジトリが増えるし同じようなことをそれぞれに更新かけたりがだるいので。 ↩

yaakai.to

docs を管理する Skill を作って (A)DR + 数個の Markdown で開発をしている

仕様駆動開発風のオレオレ実装計画を作って AI と併走する - yaakai.to

ディレクトリ

ADR と ARCHITECTURE.md を書くための Skill

ADR

ARCHITECTURE.md

esbuild/docs/architecture.md at main · evanw/esbuild

CLAUDE.md

README.md

周辺

/discuss Skill

JavaScript is not available.

claude-code/dig/commands/dig.md at master · fumiya-kume/claude-code

要件定義を行うための、Claude Code用カスタムスラッシュコマンド

Claude Code on the web

ADR の実装

GitHub Agentic Workflows

GitHub Agentic Workflows を使ってみる - yaakai.to

雑感

GitHub Agentic Workflows と通常の workflow を連携させたい

safe-outputs.dispatch-workflow

Safe Outputs | GitHub Agentic Workflows

reusable workflow

Safe Outputs | GitHub Agentic Workflows

feat: expose safe-output results as workflow_call outputs by Copilot · Pull Request #18914 · github/gh-aw

safe-outputs.github-token

GitHub Agentic Workflows を使ってみる

Automate repository tasks with GitHub Agentic Workflows

GitHub Agentic Workflowsを発表 - リポジトリの自動化を実現

Authentication | GitHub Agentic Workflows

Refs

Creating Agentic Workflows | GitHub Agentic Workflows

Custom Slash Command を Skills に変換する

Extend Claude with skills - Claude Code Docs

Claude Code on the web / on desktop 向けの設定をした

ウェブ上の Claude Code - Claude Code Docs

Claude Code Desktop を使用する - Claude Code Docs

連携する GitHub アカウントを分ける

DevContainer に ssh する

Build software better, together

SessionStart で依存の install

ウェブ上の Claude Code - Claude Code Docs

.worktreeinclude

Claude Code Desktop を使用する - Claude Code Docs

PR のフォーマットを指定する

2026/03/09 追記

Previews for Claude Code

今の運用と雑感

その他

claude-agent-sdk の output_format を zod で指定して任意の出力形式にする

Get structured output from agents

JSON Schema | Zod

Structured output ignored · Issue #105 · anthropics/claude-agent-sdk-typescript

code-simplifier が便利

claude-plugins-official/plugins/code-simplifier/agents/code-simplifier.md at main · anthropics/claude-plugins-official

JavaScript is not available.

Claude Code で respectGitignore を設定して個人用ファイルを @ で補完できるようにする

claude-code/CHANGELOG.md at main · anthropics/claude-code

[FEATURE REQUEST] Allow Claude Code to access gitignored files · Issue #2305 · anthropics/claude-code

[FEATURE REQUEST] Allow Claude Code to access gitignored files · Issue #5105 · anthropics/claude-code

仕様駆動開発風のオレオレ実装計画を作って AI と併走する - yaakai.to

Claude Code で LSP サポートを使う

claude-code/CHANGELOG.md at main · anthropics/claude-code

claude-plugins-official/plugins/typescript-lsp at main · anthropics/claude-plugins-official

Claude Code の言語を settings.json で設定する

claude-code/CHANGELOG.md at main · anthropics/claude-code

Issue 起点の開発フローを claude-code-action と CodeRabbit で作った

やっていること

Why CodeRabbit?

AIコードレビュー | CodeRabbit | 無料トライアル可能

AI Code Review | Greptile | Merge 4X Faster, Catch 3X More Bugs

Examples

パンくずリストの実装 · Issue #122 · yaakaito/yaakaito

パンくずリストの実装 by nullkite · Pull Request #125 · yaakaito/yaakaito

注釈は Pop Over で Top Layer に出すようにする by nullkite · Pull Request #127 · yaakaito/yaakaito

GitHub Actions の workflow

雑感

CLAUDE.md を作る skill を作って整理する

File not found · yaakaito/env

`/discuss` Skill

`safe-outputs.dispatch-workflow`

`safe-outputs.github-token`

AI エージェント用の Chrome DevTools（MCP） | Blog | Chrome for Developers

ポート転送でローカルサーバーと Chrome インスタンスにアクセスする | Chrome DevTools | Chrome for Developers

セキュリティを強化するためのリモートデバッグスイッチの変更 | Blog | Chrome for Developers

実用品を作って探る生成AIを使ったソフトウェア開発の現在 - 電通総研テックブログ

`/dev-plan:new`

`/dev-plan:create-md`

`/dev-plan:next`