macOS, Windows, Linux 向けの高速・軽量なMarkdownワークスペース — Rustとeguiで構築。
English | 日本語
--- ## KatanA とは **KatanA** という名前は、日本語の **「刀（かたな）」** に由来しています。精密に鍛え上げられた、鋭利な刃物です。 開発における複雑な課題を、刀のように **鋭く、的確に切り崩していきたい** — そんな思いからこのプロジェクトは命名されました。問題をひとつずつ、切れ味よく解決していくためのツールでありたいという願いが込められています。 KatanA Desktop は、仕様書や技術ドキュメントを扱う開発者のために設計された、macOS, Windows, Linux向けの高速・軽量なMarkdownワークスペースです。 末尾の大文字 **A** は **「AI」** と **「Agent」** を表しています。KatanA は AIエージェントと共に仕様駆動開発を行う時代のために設計されたツールであり、Markdownの仕様書が人間と AI の橋渡しとなる世界を見据えています。**Katana × AI Agent = KatanA.** --- ## 背景 **2026年**現在、ソフトウェア開発は **AIエージェント** の台頭により急速に進化しています。AIがコードの作成、レビュー、メンテナンスを支援する時代です。 この流れと並行して、**仕様駆動開発（SDD: Spec-Driven Development）** が注目されています。実装の前に仕様、アーキテクチャ記述、タスクを定義する開発手法であり、これらの仕様は通常 **Markdownドキュメント** として記述され、開発者とAIエージェント双方の共通基盤となります。 このリポジトリは、AIエージェントの活用を前提とした開発フローで運用されています。owner は主たる開発エージェントとして [Antigravity](https://antigravity.google/) を利用します。 リポジトリローカルの skill は `.agents/skills/` を正本として管理します。 他のAIエージェントが別の skill ディレクトリ階層を要求する場合は、`.agents/skills/` の同一内容をその期待パスへコピーして対応し、派生版を別管理しません。 運用上の習熟と保守の優先順位は Antigravity を基準にします。 ### AIエージェント開発における必須ツール トークン消費の抑制とコンテキストウィンドウの肥大化を防ぐため、本リポジトリで活動するすべてのAIエージェントには **[rtk](https://github.com/fission-ai/rtk)** の利用が **必須** 化されています。 AIエージェントは、テスト、リンター、ビルドなどの出力が多いコマンドを実行する際、必ず `rtk` でラップして出力をフィルタリング・要約してから取り込む必要があります。 しかし、既存のMarkdownツールの多くは： - 技術ドキュメントのワークフローに最適化されていない汎用エディタか、 - 不必要に複雑な重量級のナレッジ管理ツールのどちらかです。 **KatanA Desktopはこの問題を解決するために生まれました。** KatanAの目標は、**シンプルで高速、ワークスペース指向のMarkdown環境** を提供し、開発者がSDDワークフローで使用するドキュメントを簡単に **閲覧・編集** できるようにすることです。 --- ## 主な機能 - **ライブスプリットビュープレビュー** — 左側で編集、右側でレンダリング結果をスクロール同期しながら表示 - **ダイアグラムレンダリング** — Mermaid、PlantUML、Draw.ioのフェンスコードブロックをファーストクラスでサポート - **GitHub Flavored Markdown** — テーブル、取り消し線、タスクリスト、脚注、自動リンク - **ワークスペース対応** — フォルダを開き、統合ファイルツリーからファイルをナビゲーション - **タブバー** — VSCodeスタイルのタブで複数ドキュメントを同時に開く - **i18n（国際化）** — UI文字列は完全にローカライズ済み（英語・日本語同梱） - **高速なネイティブパフォーマンス** — Rustとeguiでビルドされたネイティブバイナリ。Electron不要、Node.js不要 --- ## インストール > macOS (Apple Silicon / Intel), Windows, Linux で利用可能です。 ### macOS #### Homebrew（macOS推奨） ```sh brew tap HiroyukiFuruno/KatanA && brew install --cask katana-desktop ``` 追加の手順は不要で、すぐに使い始められます。 #### 手動ダウンロード (macOS) 1. [Releasesページ](https://github.com/HiroyukiFuruno/KatanA/releases/latest) にアクセス 2. 最新の `KatanA-Desktop-x.y.z.dmg` をダウンロード 3. DMGを開き、**KatanA Desktop.app** を **アプリケーション** フォルダにドラッグ 4. 以下のコマンドを1回実行して、アプリの起動を許可してください： ```sh xattr -cr /Applications/KatanA\ Desktop.app ``` > **注意:** macOS Sequoia（15.x）では、Appleの公証を受けていないアプリの起動にこのコマンドが必要です。 > または、初回起動を試みた後に **システム設定 → プライバシーとセキュリティ → 「このまま開く」** からも許可できます。 ### Windows #### ポータブル ZIP（推奨） 1. [Releasesページ](https://github.com/HiroyukiFuruno/KatanA/releases/latest) にアクセス 2. `KatanA-windows-x86_64.zip` をダウンロード 3. 任意の場所に展開（例: `C:\Program Files\KatanA\`） 4. `katana-desktop.exe` を実行 > **ヒント:** タスクバーにピン留めするか、デスクトップにショートカットを作成すると便利です。 #### MSI インストーラー (Windows) MSI インストーラー (`KatanA-windows-x86_64.msi`) も [Releasesページ](https://github.com/HiroyukiFuruno/KatanA/releases/latest) から入手できます。スタートメニューとデスクトップにショートカットが自動作成されます。 > **注意:** MSI はコード署名されていないため、ダウンロード時に Windows SmartScreen の警告が表示されることがあります。 > Edge の場合、ダウンロードバーで **「…」→「保持する」** をクリックしてください。さらにダイアログが表示された場合は **「詳細表示」→「保持する」** を選択してください。 ### Linux #### Homebrew (推奨) ```sh brew tap HiroyukiFuruno/KatanA && brew install katana-desktop ``` #### 手動ダウンロード (Linux) 1. [Releasesページ](https://github.com/HiroyukiFuruno/KatanA/releases/latest) にアクセス 2. `KatanA-linux-x86_64.tar.gz` をダウンロード 3. アーカイブを展開し、実行ファイルを起動 ### アプリのアップデート KatanA Desktop には自動アップデータが内蔵されています。一度インストールすれば（Homebrew経由でも手動でも）、新しいリリースが利用可能になった際に通知されます。 - **macOS:** アプリ内の **"Update & Restart"** ボタンをクリックするだけで自動的に更新されます。Homebrew経由で初回インストールした場合、アプリ内から初めてアップデートを行った際に、二重管理を防ぐため自動的に `brew untap` されます。 - **Windows / Linux:** アップデート時のダイアログから、最新のアセットをダウンロードするための Release ページリンクが表示されます。 --- ## 現在のステータス KatanA Desktop は **活発に開発中** です。最新バージョンと変更履歴は [Releasesページ](https://github.com/HiroyukiFuruno/KatanA/releases/latest) をご覧ください。 現在利用可能な主な機能： - ワークスペースベースのMarkdown閲覧 - ダイアグラムサポート（Mermaid / PlantUML / draw.io） - スクロール同期付きスプリットプレビュー - 高速なネイティブデスクトップパフォーマンス（Rustベース） プロジェクトは急速に進化しており、新機能や改善が頻繁にリリースされています。 --- ## ダイアグラム表示の準備 KatanA は Markdown のフェンスコードブロック内の Mermaid、PlantUML、Draw.io ダイアグラムをサポートしています。Mermaid と PlantUML のレンダリングには外部ツールが必要です。 ### Mermaid Mermaid CLI をグローバルにインストールしてください： ```sh npm i -g @mermaid-js/mermaid-cli ``` インストール後、`mmdc` は自動的に検出されます。追加の設定は不要です。 ### PlantUML 1. Java ランタイムをインストール： ```sh brew install openjdk@25 ``` 1. PlantUML ブロックを含む Markdown ファイルを KatanA で開き、プレビューペインに表示される **⬇ ダウンロード** ボタンをクリックしてください。`plantuml.jar` が自動的にダウンロードされます。 ### Draw.io Draw.io ダイアグラムはネイティブでレンダリングされます — 外部ツールは不要です。 --- ## プロジェクトの目標 KatanAは開発者が以下を実現するためのツールを目指しています： - Markdownドキュメントを効率的に閲覧・ナビゲーション - 仕様駆動ワークフローとの連携 - 現代的なAIアシスト開発とのドキュメント統合 長期的なビジョンは、モダンな開発ツールを補完する **軽量なドキュメントワークスペース** の構築です。 --- ## アイデアを募集しています このプロジェクトはまだ初期段階にあります。機能のアイデア、使い勝手の提案、バグ報告などを歓迎します。 KatanAが開発者のドキュメントワークフローをどのように改善できるかアイデアがあれば、ぜひ[issue](https://github.com/HiroyukiFuruno/KatanA/issues)や[discussion](https://github.com/HiroyukiFuruno/KatanA/discussions)を開いてください。 --- ## コントリビューター向け KatanA の未来を一緒に形作っていきたい方は、ぜひ以下をお読みください： - 🤝 **[Contributing Guide](CONTRIBUTING.ja.md)** — ディスカッションへの参加方法、デザインへのフィードバック提供、AIエージェント支援ワークフローによる協力方法について。 --- ## オープンソースへのコミットメント KatanA Desktopはオープンソースプロジェクトです。 **コアな機能を無料で提供し続ける** ことをお約束します。特に運用コストがかからない機能については： - Markdownの閲覧 - ワークスペースナビゲーション - ドキュメントブラウジング - ダイアグラムレンダリング --- ## 今後の展望 一部の高度な機能は外部サービスや運用コストが必要になる可能性があります。 持続可能性のために、プロジェクトは以下を導入する可能性があります： - オプションの有料機能（例: AIアシストツール） - アプリケーション内の小規模な広告 ただし、**コアなドキュメント機能は引き続き無料** です。 --- ## 開発者の方へ ソースからビルドしたい方、コントリビュートしたい方、アーキテクチャを理解したい方へ： - 📖 **[開発ガイド](docs/development-guide.ja.md)** — セットアップ、ビルド、テスト、プロジェクト構造 - 📐 **[コーディング規約](docs/coding-rules.ja.md)** — コードスタイル、規約、品質ゲート - 🏗️ **[Architecture Decisions](docs/adr/)** — 設計の根拠とADR --- ## プロジェクトを支援する KatanAが役に立ったと思っていただけたら、スポンサーシップで開発を支援できます。
支援は以下に活用されます：
- 開発時間
- インフラ
- ツール費用
👉 **[スポンサーになる](https://github.com/sponsors/HiroyukiFuruno)**
- ⭐ このリポジトリにスターをつける — 他の人がKatanAを見つけるのに役立ちます
- KatanAを役立ててくれそうな人にシェアする
---
## 付録: Windows 環境セットアップ
ダイアグラムレンダリング（Mermaid / PlantUML）に必要な外部ツールの Windows でのインストール手順です。