HN 日本語サマリー

← 一覧へ戻る
プログラミング

Show HN: Treedocs: 古くなったドキュメントを自動で検出

Show HN: Treedocs: Documentation that automatically checks for staleness (dandylyons.github.io)

13 pointsby DandyLyons8 コメント

要約

Treedocsは、新しいチームメイト、将来の自分、そしてコーディングエージェントが複雑なリポジトリを迅速に理解できるよう、簡潔なコンテキストを提供します。自動的なドリフトチェックによりドキュメントの陳腐化を防ぎ、警告や失敗の通知を出すことで常に最新の状態を保ちます。さらに、シンプルな要約をtreedocs.yamlに保存することで、レビューを容易にし、AIエージェントがプロジェクト構造を再発見する手間を省きます。

全文翻訳

treedocs

Swift CLI

ドキュメント化されたtreeを各ファイルとフォルダに自動生成することで、どんなコードベースでもより速く理解できるようになります。

treedocs デモビデオ

読みやすいツリー出力

treedocsを実行するだけで、リポジトリを一目で確認できます。現在のファイルは緑色で表示され、古いまたは無効なエントリは赤色で表示されるため、問題がすぐに際立ちます。

✅ 以下の treedocs はファイルシステムと同期しています。
. 
├── README.md  ユーザー向けの概要、インストール方法、コマンド使用方法に関するドキュメント。
├── Sources/  treedocs 実行可能ファイルのための Swift パッケージソースコード。
│   └── treedocs/  メインの treedocs 実行可能ターゲット。
│       ├── Commands/  treedocs サブコマンドのための ArgumentParser コマンド実装。
│       └── Core/  treedocs データのロード、スキャン、レンダリング、更新のためのコアサービス。
├── site/  プロジェクトの GitHub Pages サイトにデプロイされる静的ファイル。
│   ├── index.html  treedocs GitHub Pages サイトのランディングページ。
│   └── styles.css  treedocs GitHub Pages ランディングページのスタイルシート。
└── old-file.swift  古いエントリ: ディスク上に一致するパスが存在しません。

より速く慣れる

新しいチームメイト、将来の自分、コーディングエージェントに、複雑なリポジトリを理解するために必要な簡潔なコンテキストを提供し、無目的にさまよう必要がなくなります。

最新の状態を維持する

自動的なドリフトチェックでドキュメントが古くなるのを防ぎ、警告または失敗させます。ドキュメント化されていない変更をコミットしないように、Git の pre-commit フックをインストールすることもできます。

コンテキスト付きレビュー

シンプルで人間が読める、バージョン管理された要約を treedocs.yaml に保存することで、レビューが容易になり、エージェントはプロジェクト構造の再発見に費やすトークンを節約できます。

インストール

treedocs は現在 macOS 13 以降をサポートしています。バージョン 0.2.0 はソースビルドのみであるため、Homebrew、Mint、または mise を介したインストールには Swift 6 対応のビルド環境(通常は Xcode 16+)が必要です。

mise

MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/treedocs@0.2.0

mise は Swift Package Manager バックエンドを使用します。treedocs は現在アーティファクトバンドルを公開していないため、mise はソースからビルドします。mise の spm: バックエンドは現在実験的であるため、インストール時に MISE_EXPERIMENTAL=true を設定してください。

Homebrew

brew install DandyLyons/tap/treedocs

Homebrew のフォーミュラは、DandyLyons タップを通じてソースから treedocs をビルドします。

Mint

mint install DandyLyons/treedocs@0.2.0
mint run DandyLyons/treedocs@0.2.0 --help

Mint は、タグ付けされた GitHub ソースから Swift 実行可能パッケージをビルドします。

クイックスタート


treedocs init      # treedocs.yaml ファイルを作成します
treedocs sync      # treedocs.yaml を現在のフォルダ構造と同期し、エラーをチェックします。
treedocs show .    # ドキュメント化されたツリーを表示します
treedocs check     # treedocs.yaml のエラーをチェックします。
treedocs explore . # コードベースの段階的開示による探索。エージェントによる探索に最適です。

treedocs.yaml スキーマ

treedocs.yaml は、リポジトリのバージョン管理されたマップです。ファイルツリーをミラーリングし、各ファイルとフォルダの人間が読める YAML 説明を保存します。この同じ説明は、treedocs のリッチなツールで解析および表示できます。ファイル形式は 正規の JSON スキーマ によって定義されているため、エディタ、CI ツール、AI エージェントはすべて同じ構造を解析、検証、理解できます。

ドキュメントを最新の状態に保つのは継続的なタスクですが、treedocs がそれを容易にします!treedocs sync を実行すると、treedocs.yaml ファイルが更新され、新しいパスが追加され、ゴーストパスが削除されます。残りは短い説明を追加することだけです。treedocs update を使用すると、説明を簡単に更新できます。

または、エージェントに treedocs.yaml ファイルを埋めてもらうように依頼するだけです。エージェントは説明の記入に非常に優れており、すべて treedocs check で検証できます。