Skip to content

Commit ea57b89

Browse files
Tomatio13Tomatio13
committed
feat: add static knowledge site
0 parents  commit ea57b89

9 files changed

Lines changed: 1216 additions & 0 deletions

File tree

‎.github/workflows/static.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy Static Site
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
deploy:
20+
runs-on: ubuntu-latest
21+
environment:
22+
name: github-pages
23+
url: ${{ steps.deployment.outputs.page_url }}
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Setup Pages
29+
uses: actions/configure-pages@v5
30+
31+
- name: Upload artifact
32+
uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: .
35+
36+
- name: Deploy to GitHub Pages
37+
id: deployment
38+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.firecrawl/
2+
.DS_Store

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# 技術ノート運用ルール
2+
3+
## 目的
4+
5+
- 技術的な疑問を、あとで読み返せる静的 HTML 記事として残す
6+
- 1テーマ1ページで `articles/` に蓄積する
7+
- `index.html` から新着とカテゴリの両方で辿れるようにする
8+
9+
## 記事生成ルール
10+
11+
- ユーザーが `質問:` で始めた依頼は、記事化タスクとして扱う
12+
- 出力先は `articles/<slug>.html` とする
13+
- 各記事には以下を含める
14+
- タイトル
15+
- 要点
16+
- 本文
17+
- 比較や図解に相当する要素
18+
- 参考URL
19+
- 作成日
20+
- HTML は単体で読める形にし、共通スタイルは `styles/site.css` を使う
21+
- 記事ごとに最低1つは図を入れる
22+
- 図は装飾ではなく、流れ、比較、構造の理解を早めるために使う
23+
- 図解が必要なら、まずは HTML と CSS だけで表現し、必要時は inline SVG を優先する
24+
25+
## 一次情報と安全性
26+
27+
- 参考URLは必ず末尾に付ける
28+
- 仕様、価格、法令、リリース状況など変化しやすい情報は一次情報を優先する
29+
- 秘匿情報、認証情報、個人情報は記事に含めない
30+
- 公開前に差分を人間が確認する
31+
32+
## トップページ更新ルール
33+
34+
- 新しい記事を追加したら `index.html` も更新する
35+
- 最低限、以下の両方を更新する
36+
- 新着セクション
37+
- 対応カテゴリのセクション
38+
- カードには以下を含める
39+
- 日付
40+
- 小分類
41+
- タイトル
42+
- 1文要約
43+
- 補助メタ情報
44+
45+
## GitHub Pages 想定
46+
47+
- このリポジトリはビルド不要の静的サイトとして運用する
48+
- 配信対象は HTML、CSS、画像など公開前提のファイルに限る
49+
- 機密につながる JSON、YAML、env は置かない

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# techNote
2+
3+
スマホや PC で投げた技術的な疑問を、静的 HTML 記事として蓄積するための最小構成です。
4+
5+
## 構成
6+
7+
- `index.html`: 新着とカテゴリ一覧を持つトップページ
8+
- `articles/`: 個別記事
9+
- `styles/site.css`: 共通スタイル
10+
- `AGENTS.md`: Codex 向けの記事生成ルール
11+
12+
## 公開方法
13+
14+
GitHub Pages などの静的ホスティングにそのまま配置できます。
15+
16+
## 運用イメージ
17+
18+
1. `質問:` で始まる依頼を Codex に渡す
19+
2. `articles/` に HTML を追加する
20+
3. `index.html` にカードを追記する
21+
4. 差分確認後に公開する

‎articles/codegraph.html‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
<!doctype html>
2+
<html lang="ja">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>CodeGraphとは何か</title>
7+
<link rel="stylesheet" href="../styles/site.css">
8+
</head>
9+
<body>
10+
<main class="article-page">
11+
<a class="back-link" href="../index.html">← 一覧へ戻る</a>
12+
13+
<article class="article-shell">
14+
<p class="eyebrow">AI / コード探索</p>
15+
<h1>CodeGraphとは何か</h1>
16+
<p class="article-date">作成日: 2026年6月14日</p>
17+
18+
<section>
19+
<h2>要点</h2>
20+
<ul>
21+
<li>CodeGraph は、コードベースをローカルで索引化して、エージェントが構造質問へ直接答えやすくするためのコードインテリジェンス基盤です。</li>
22+
<li>価値は「検索できること」だけではなく、MCP ツール経由で symbol、caller、callee、impact、explore をまとめて返せることにあります。</li>
23+
<li>README では auto-sync、framework-aware routes、20以上の言語対応を前面に出しており、実装上も `CodeGraph` クラスが抽出、解決、探索、文脈生成、DB を束ねています。</li>
24+
</ul>
25+
</section>
26+
27+
<section>
28+
<h2>何をするツールか</h2>
29+
<p>CodeGraph は、`grep` とファイル読みを何度も繰り返す代わりに、あらかじめ構築したローカル索引からコード構造を返すための仕組みです。README では「semantic code intelligence」「100% local」を打ち出していて、エージェントに MCP server をつなぐ形で使います。</p>
30+
<figure class="diagram-card">
31+
<svg viewBox="0 0 920 230" role="img" aria-label="CodeGraphの基本フロー">
32+
<rect x="20" y="55" width="190" height="120" rx="22" fill="#fff7ed" stroke="#c2410c" stroke-width="2"/>
33+
<text x="115" y="98" text-anchor="middle" font-size="28" font-weight="700" fill="#9a3412">コードベース</text>
34+
<text x="115" y="132" text-anchor="middle" font-size="20" fill="#7c2d12">TypeScript</text>
35+
<text x="115" y="158" text-anchor="middle" font-size="20" fill="#7c2d12">Python / Go / Rust...</text>
36+
37+
<path d="M210 115 H330" stroke="#9ca3af" stroke-width="4" stroke-linecap="round"/>
38+
<polygon points="330,115 312,105 312,125" fill="#9ca3af"/>
39+
40+
<rect x="330" y="35" width="240" height="160" rx="22" fill="#fafaf9" stroke="#57534e" stroke-width="2"/>
41+
<text x="450" y="78" text-anchor="middle" font-size="28" font-weight="700" fill="#1c1917">CodeGraph</text>
42+
<text x="450" y="112" text-anchor="middle" font-size="20" fill="#44403c">index</text>
43+
<text x="450" y="138" text-anchor="middle" font-size="20" fill="#44403c">reference resolve</text>
44+
<text x="450" y="164" text-anchor="middle" font-size="20" fill="#44403c">context build</text>
45+
46+
<path d="M570 115 H690" stroke="#9ca3af" stroke-width="4" stroke-linecap="round"/>
47+
<polygon points="690,115 672,105 672,125" fill="#9ca3af"/>
48+
49+
<rect x="690" y="35" width="210" height="54" rx="18" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
50+
<text x="795" y="68" text-anchor="middle" font-size="20" font-weight="700" fill="#1d4ed8">MCP tools</text>
51+
52+
<rect x="690" y="103" width="210" height="54" rx="18" fill="#f0fdfa" stroke="#0f766e" stroke-width="2"/>
53+
<text x="795" y="136" text-anchor="middle" font-size="20" font-weight="700" fill="#0f766e">codegraph_explore</text>
54+
55+
<rect x="690" y="171" width="210" height="34" rx="16" fill="#f5f3ff" stroke="#7c3aed" stroke-width="2"/>
56+
<text x="795" y="193" text-anchor="middle" font-size="16" font-weight="700" fill="#6d28d9">search / callers / impact</text>
57+
</svg>
58+
<figcaption class="diagram-caption">コードを前もって索引化し、その結果を MCP ツールとしてエージェントへ返す構造です。</figcaption>
59+
</figure>
60+
</section>
61+
62+
<section>
63+
<h2>何がうれしいか</h2>
64+
<div class="mini-grid">
65+
<div class="mini-card">
66+
<h3>探索が短い</h3>
67+
<p>構造質問を `codegraph_explore` などで直接引けるので、探索用の grep が減ります。</p>
68+
</div>
69+
<div class="mini-card">
70+
<h3>ローカル完結</h3>
71+
<p>README では SQLite ベースの 100% local を前面に出しています。</p>
72+
</div>
73+
<div class="mini-card">
74+
<h3>編集後も追随</h3>
75+
<p>watcher と connect-time catch-up により索引の古さを抑えます。</p>
76+
</div>
77+
</div>
78+
<figure class="diagram-card">
79+
<svg viewBox="0 0 920 250" role="img" aria-label="通常探索とCodeGraph利用の違い">
80+
<rect x="30" y="25" width="380" height="190" rx="24" fill="#fff7ed" stroke="#c2410c" stroke-width="2"/>
81+
<text x="220" y="62" text-anchor="middle" font-size="28" font-weight="700" fill="#9a3412">CodeGraphなし</text>
82+
<text x="220" y="102" text-anchor="middle" font-size="20" fill="#7c2d12">find / grep / read</text>
83+
<text x="220" y="130" text-anchor="middle" font-size="20" fill="#7c2d12">↓</text>
84+
<text x="220" y="158" text-anchor="middle" font-size="20" fill="#7c2d12">候補を何度も絞る</text>
85+
<text x="220" y="186" text-anchor="middle" font-size="20" fill="#7c2d12">探索コストが増える</text>
86+
87+
<rect x="510" y="25" width="380" height="190" rx="24" fill="#f0fdfa" stroke="#0f766e" stroke-width="2"/>
88+
<text x="700" y="62" text-anchor="middle" font-size="28" font-weight="700" fill="#0f766e">CodeGraphあり</text>
89+
<text x="700" y="102" text-anchor="middle" font-size="20" fill="#115e59">explore / node / callers</text>
90+
<text x="700" y="130" text-anchor="middle" font-size="20" fill="#115e59">↓</text>
91+
<text x="700" y="158" text-anchor="middle" font-size="20" fill="#115e59">構造化された答えを返す</text>
92+
<text x="700" y="186" text-anchor="middle" font-size="20" fill="#115e59">探索回数を減らせる</text>
93+
</svg>
94+
<figcaption class="diagram-caption">価値の中心は「検索が少し速い」ではなく、「構造質問の入口が直接用意される」ことです。</figcaption>
95+
</figure>
96+
</section>
97+
98+
<section>
99+
<h2>公開されている主なツール面</h2>
100+
<ul>
101+
<li><code>codegraph_explore</code>: 構造質問の主入口</li>
102+
<li><code>codegraph_search</code>: symbol を探す</li>
103+
<li><code>codegraph_callers</code> / <code>codegraph_callees</code>: 呼び出し関係を辿る</li>
104+
<li><code>codegraph_impact</code>: 変更影響をみる</li>
105+
<li><code>codegraph_node</code>: 特定 symbol のソースを引く</li>
106+
<li><code>codegraph_status</code> / <code>codegraph_files</code>: 索引状態や対象ファイルを確認する</li>
107+
</ul>
108+
</section>
109+
110+
<section>
111+
<h2>内部はどう分かれているか</h2>
112+
<p>メモと `src/index.ts` を見る限り、`CodeGraph` クラスが主要コンポーネントを束ねる構造です。説明しやすい分け方は、抽出、参照解決、探索、文脈生成、保存の5つです。</p>
113+
<figure class="diagram-card">
114+
<svg viewBox="0 0 920 300" role="img" aria-label="CodeGraphの内部構成">
115+
<rect x="300" y="20" width="320" height="62" rx="22" fill="#fafaf9" stroke="#57534e" stroke-width="2"/>
116+
<text x="460" y="58" text-anchor="middle" font-size="28" font-weight="700" fill="#1c1917">CodeGraph class</text>
117+
118+
<rect x="40" y="120" width="240" height="58" rx="18" fill="#fff7ed" stroke="#c2410c" stroke-width="2"/>
119+
<text x="160" y="155" text-anchor="middle" font-size="20" font-weight="700" fill="#9a3412">ExtractionOrchestrator</text>
120+
121+
<rect x="340" y="120" width="240" height="58" rx="18" fill="#fefce8" stroke="#ca8a04" stroke-width="2"/>
122+
<text x="460" y="155" text-anchor="middle" font-size="20" font-weight="700" fill="#a16207">ReferenceResolver</text>
123+
124+
<rect x="640" y="120" width="240" height="58" rx="18" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
125+
<text x="760" y="155" text-anchor="middle" font-size="20" font-weight="700" fill="#1d4ed8">GraphQueryManager</text>
126+
127+
<rect x="190" y="220" width="240" height="58" rx="18" fill="#f0fdfa" stroke="#0f766e" stroke-width="2"/>
128+
<text x="310" y="255" text-anchor="middle" font-size="20" font-weight="700" fill="#0f766e">GraphTraverser</text>
129+
130+
<rect x="490" y="220" width="240" height="58" rx="18" fill="#f5f3ff" stroke="#7c3aed" stroke-width="2"/>
131+
<text x="610" y="255" text-anchor="middle" font-size="20" font-weight="700" fill="#6d28d9">ContextBuilder</text>
132+
133+
<rect x="720" y="220" width="160" height="58" rx="18" fill="#ecfeff" stroke="#0891b2" stroke-width="2"/>
134+
<text x="800" y="255" text-anchor="middle" font-size="20" font-weight="700" fill="#0e7490">DB</text>
135+
136+
<line x1="460" y1="82" x2="160" y2="120" stroke="#9ca3af" stroke-width="3"/>
137+
<line x1="460" y1="82" x2="460" y2="120" stroke="#9ca3af" stroke-width="3"/>
138+
<line x1="460" y1="82" x2="760" y2="120" stroke="#9ca3af" stroke-width="3"/>
139+
<line x1="460" y1="178" x2="310" y2="220" stroke="#9ca3af" stroke-width="3"/>
140+
<line x1="460" y1="178" x2="610" y2="220" stroke="#9ca3af" stroke-width="3"/>
141+
<line x1="760" y1="178" x2="800" y2="220" stroke="#9ca3af" stroke-width="3"/>
142+
</svg>
143+
<figcaption class="diagram-caption">抽出して、参照を解決し、問い合わせや文脈生成に使い、その結果をローカル DB に載せる構造です。</figcaption>
144+
</figure>
145+
</section>
146+
147+
<section>
148+
<h2>扱うデータの考え方</h2>
149+
<ul>
150+
<li><strong>nodes</strong>: file、class、function、route、component などのコード要素</li>
151+
<li><strong>edges</strong>: contains、calls、imports、references などの関係</li>
152+
<li><strong>unresolved_refs</strong>: まだ解決しきれていない参照</li>
153+
</ul>
154+
<div class="compare-box">
155+
<p>ただの全文索引ではなく、構造化ノードと関係エッジを持つので、caller や impact のような質問に向いています。</p>
156+
</div>
157+
</section>
158+
159+
<section>
160+
<h2>使い始める流れ</h2>
161+
<ol>
162+
<li><code>codegraph install</code> で agent 側の MCP 設定を入れる</li>
163+
<li>対象リポジトリで <code>codegraph init -i</code> を実行する</li>
164+
<li>`.codegraph/` ができたら、agent から `codegraph_explore` などを使う</li>
165+
<li>編集後は watcher と connect-time catch-up で索引を追随させる</li>
166+
</ol>
167+
<figure class="diagram-card">
168+
<svg viewBox="0 0 920 180" role="img" aria-label="CodeGraphの導入手順">
169+
<rect x="20" y="55" width="170" height="70" rx="20" fill="#fff7ed" stroke="#c2410c" stroke-width="2"/>
170+
<text x="105" y="97" text-anchor="middle" font-size="20" font-weight="700" fill="#9a3412">install</text>
171+
<path d="M190 90 H260" stroke="#9ca3af" stroke-width="4" stroke-linecap="round"/>
172+
<polygon points="260,90 242,80 242,100" fill="#9ca3af"/>
173+
174+
<rect x="260" y="55" width="170" height="70" rx="20" fill="#fefce8" stroke="#ca8a04" stroke-width="2"/>
175+
<text x="345" y="97" text-anchor="middle" font-size="20" font-weight="700" fill="#a16207">init -i</text>
176+
<path d="M430 90 H500" stroke="#9ca3af" stroke-width="4" stroke-linecap="round"/>
177+
<polygon points="500,90 482,80 482,100" fill="#9ca3af"/>
178+
179+
<rect x="500" y="55" width="170" height="70" rx="20" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
180+
<text x="585" y="97" text-anchor="middle" font-size="20" font-weight="700" fill="#1d4ed8">explore</text>
181+
<path d="M670 90 H740" stroke="#9ca3af" stroke-width="4" stroke-linecap="round"/>
182+
<polygon points="740,90 722,80 722,100" fill="#9ca3af"/>
183+
184+
<rect x="740" y="55" width="160" height="70" rx="20" fill="#f0fdfa" stroke="#0f766e" stroke-width="2"/>
185+
<text x="820" y="97" text-anchor="middle" font-size="20" font-weight="700" fill="#0f766e">auto-sync</text>
186+
</svg>
187+
<figcaption class="diagram-caption">最初に install と init を済ませると、あとは explore 系を入口にして使い続けやすくなります。</figcaption>
188+
</figure>
189+
</section>
190+
191+
<section>
192+
<h2>向いている場面</h2>
193+
<ul>
194+
<li>大きめのリポジトリで、毎回 grep と Read を繰り返すのが重いとき</li>
195+
<li>call flow、route、impact のような構造質問が多いとき</li>
196+
<li>Claude Code、Codex、Cursor など複数 agent に同じ索引を使わせたいとき</li>
197+
</ul>
198+
</section>
199+
200+
<section>
201+
<h2>まとめ</h2>
202+
<p>CodeGraph は、コードをローカルで索引化し、エージェントに構造化された入口を与えるための基盤です。強みは単なる検索速度ではなく、`explore`、`callers`、`impact` のようなコード理解用ツール面と、watcher を含む継続運用のしやすさにあります。</p>
203+
</section>
204+
205+
<section>
206+
<h2>参考URL</h2>
207+
<ul>
208+
<li><a href="https://github.com/colbymchenry/codegraph">CodeGraph GitHub repository</a></li>
209+
<li><a href="https://colbymchenry.github.io/codegraph/">CodeGraph documentation site</a></li>
210+
</ul>
211+
</section>
212+
</article>
213+
</main>
214+
</body>
215+
</html>

0 commit comments

Comments
 (0)