How I wrote JustHTML, a Python-based HTML5 parser, using coding agents

私は最近 JustHTML をリリースしました。これは Python で書かれた HTML5 パーサーで、html5lib のテストスイートを 100 % 通過し、依存パッケージが一切なく、CSS セレクタ検索 API も備えています。この実装を書き上げる過程で、コーディングエージェントと効果的に協働する方法について多くのことを学びました。

なぜ HTML5？

• テストが豊富なプロジェクト を選ぶことで、エージェントのトレーニングが最適化されます。
• HTML5 の仕様は十分に定義済みであり、

  html5lib-tests

  リポジトリには数千ものトークナイザ・ツリービルダー用テストが揃っています。
• 完全なテストスイートを持つことで、エージェント自身が進捗を確認し、失敗箇所を把握して改善に繰り返し取り組めます。

パーサーの構築（反復・再起動・性能向上）

1. ワンショット HTML5 パーサー

まずエージェントに極簡易なワンショットパーサーを書かせました。うまく機能しませんでしたが、出発点にはなりました。

2.

html5lib-tests

の接続

テストを組み込んだ結果、通過率は 1 % 未満 に留まりました。これらのテストは非常に難易度が高く、数千もの境界ケースを含んでいます。

3. 約30 % 覆盖までの反復

リファクタリングとバグ修正を重ねて、徐々にカバー率を 約30 % に引き上げました。

4. タグハンドラベースへの再設計

次にハンドラ中心の構造へ切り替えました：

class TagHandler:
    """すべてのタグハンドラの基底クラス。"""
    def handle_start(self, context, token):
        pass

class UnifiedCommentHandler(TagHandler):
    """全状態でコメントを処理するハンドラ。"""
    def handle_start(self, context, token):
        context.insert_comment(token.data)

エージェントはこの設計に合わせてコードをリファクタリングしました。

5. 100 % テストカバレッジの達成

Claude Sonnet 3.7 のような強力なモデルを用いて、最終的に 完全カバー を実現しました。

ベンチマークと性能改善

• ベンチマーク: パーサーは

  html5lib

  より約 3 倍遅い。
• Rust トークナイザの書き換え: エージェントがトークナイザを Rust で再実装。速度はほぼ

  html5lib

  と同等。生成された

  rust_tokenizer

  クレートは約 690 行です。
• Html5ever の発見: Servo の

  html5ever

  は高速かつ正確な Rust 実装でした。
• プロジェクトへの疑問: 「本当に作る必要があるのか？」と自問し、削除しようとも考えました。

ピボット：html5ever のロジックを Python に移植

諦めずに、

html5ever

html5lib

性能作業

• 簡易プロファイラと 10 万件の人気ページを収集するスクレイパーを構築。
• Gemini 3 Pro を使ってベンチマーク・微調整を実施。その他のモデルでは進展がありませんでした。

def _append_text_chunk(self, chunk, *, ends_with_cr=False):
    if not chunk:
        self.ignore_lf = ends_with_cr
        return
    if self.ignore_lf:
        if chunk[0] == "\n":
            chunk = chunk[1:]

未テストコードの削除

カバレッジ分析で大きな未テスト領域を発見。これら（ツリービルダー 786 行 → 453 行）を削除することで、コードはクリーンになり速度も向上しました。

フュージングでクラッシュ検出

エージェントに HTML ファザ―を書かせました：

def generate_fuzzed_html():
    """完全にファズされた HTML ドキュメントを生成。"""
    parts = []
    if random.random() < 0.5:
        parts.append(fuzz_doctype())
    # 要素のランダム混合を生成
    num_elements = random.randint(1, 20)

ファザ―によりパーサーはクラッシュし、各失敗を修正して新しいテストとして追加。300 万件以上のページ生成後、クラッシュは残っていません。

他パーサーとの比較

• 90 % 以上通過する他パーサー: 存在しない。

• lxml

  （人気 Python パーサー）は 1 % 通過。
• 参照実装である

  html5lib

  自体が 88 % 通過。

したがって、100 % カバレッジは稀かつ困難です。

ライブラリとしての公開

エージェントに CI 設定、GitHub でのリリース、クエリ API、ドキュメント作成を任せました。使用例：

from justhtml import JustHTML, query

doc = JustHTML("<div><p>Hello</p></div>")
elements = query(doc, "div > p")

ライブラリは turbohtml から justhtml に改名されました―速度ではなく、信頼性を示すためです。

エージェントが行ったこと vs. 私の役割

• エージェント: 全コードを書き、面倒な作業を処理し、バグに対して反復。
• 私: 高レベル設計を指導し、コミットをレビューし、誤りを修正。Git のコミットはすべて自分で行い、変更ごとに検証しました。アルゴリズムの詳細までは把握できませんでしたが、間違っている点なら判断できます。

コーディングエージェントとの実務的ヒント

1. 明確かつ測定可能な目標 を設定する：「テストを通過させる」方が「コードを改善する」よりも効果的です。
2. 変更点のレビュー：生成されたコードを読んで問題点を把握し、学びます。
3. フィードバックを惜しまない：何かがおかしいと感じたら遠慮なく伝える（例：「好きではありません」）。
4. バージョン管理を活用：エージェントが逸脱した場合は戻せるようにする。
5. 失敗を許容：失敗するコマンドを実行させることで、エージェントは学習します。

価値があったか？

はい。JustHTML は約 3,000 行の Python コードで 8,500+ テストに合格しており、私はエージェントなしではそんなに早く完成できませんでした。「迅速」＝「考えない」わけではありません。コードレビューや設計判断を行い、エージェントを導きました。作業分担はうまく機能しました：エージェントが入力し、私は思考する。