0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

新人プログラマ応援 - みんなで新人を育てよう！
@yuta_yokoi_ai

AI時代のポートフォリオは人間に見せるだけでは足りない：GitHub PagesでAIOを始める実務メモ

0
Posted at

この記事は、Zennに投稿した完全版
AI時代のポートフォリオは人間に見せるだけでは全く足りない：GitHub PagesでAIOを実装し続ける実験
の要点整理です。

完全版では、HTML / llms.txt / llms-full.txt / JSON-LD / .well-known / WebP XMP / MP3 ID3 / GitHub Actions / 検証スクリプトまで含めて整理しています。

Qiita版では、まず GitHub PagesポートフォリオへAIOを入れるための最小構成 に絞ります。

この記事で言いたいこと

AI時代のポートフォリオは、人間に見せるだけでは足りません。

人間の採用担当者やエンジニアが見るだけなら、ポートフォリオは「見た目」「実績」「説明文」「リンク集」で成立します。

しかし、今後はそれだけでは不十分です。

  • AI検索
  • ChatGPT
  • Claude
  • Perplexity
  • 検索エンジンのAI要約
  • AIエージェント
  • 採用担当者が使うAI要約ツール

こうしたものが、ポートフォリオを直接・間接に読む可能性があります。

つまり、ポートフォリオは 人間向けの作品集 であると同時に、AIが読める評価構造 でもあるべきです。

完全版とQiita版の違い

種別 役割
Zenn完全版 実装詳細、検証スクリプト、WebP XMP、MP3 ID3、GitHub Actionsまで扱う重厚版
Qiita版 まず何を置き、何を構造化し、何を検証すればよいかを整理する要点版

この記事だけでも、GitHub PagesポートフォリオにAIOを入れる最初の設計は分かるようにします。

より詳細なコード、検証スクリプト、バイナリメタデータ検証まで含む完全版は以下です。

Zenn完全版：AI時代のポートフォリオは人間に見せるだけでは全く足りない

なぜGitHub PagesポートフォリオでAIOを考えるのか

GitHub Pages は、GitHubリポジトリ内のHTML / CSS / JavaScriptを公開できる静的サイトホスティングです。

ポートフォリオとの相性は非常に良いです。

一方で、通常のサーバーアプリケーションと同じようには扱えません。

項目 GitHub Pages単体での扱い
HTML / CSS / JavaScript配信 できる
Markdown / JSON / XML / txt配置 できる
画像 / 音声配置 できる
GitHub Actions検証 できる
サーバーサイド処理 原則難しい
生アクセスログ取得 難しい
WAF制御 GitHub Pages単体では難しい
動的API 原則難しい

ここが重要です。

GitHub Pagesでは、サーバー側でAI botを細かく制御することは難しい。
だからこそ、AIが読む HTML・Markdown・JSON・XML・メタデータそのもの を設計する必要があります。

AI時代のポートフォリオで見るべき層

通常のポートフォリオは、人間向けUIを中心に作られます。

しかし、AIにも読ませるなら、次のように層を分けて考えると整理しやすいです。

層 人間向け AI向け
Visible Web Layer UI / デザイン / 操作感 HTML構造 / meta / canonical
AI-readable Text Layer README / 説明文 llms.txt / llms-full.txt / AI2AI.md
Structured Data Layer 見えない JSON-LD / sitemap.xml
Discovery Layer 見えない .well-known / manifest
Binary Metadata Layer 画像 / 音声 WebP XMP / MP3 ID3
Validation Layer 手動確認 GitHub Actions / digest検証

Qiita版では、このうち最初に入れるべき最小構成に絞ります。

最小構成

GitHub PagesポートフォリオにAIOを入れるなら、まず以下を揃えるのが現実的です。

ファイル 役割
index.html 人間向けUI + AI向けmeta / JSON-LD
llms.txt AI向け入口
llms-full.txt AI向け正典
robots.txt crawler向け方針宣言
sitemap.xml URL発見導線
.well-known/llms.txt AI discovery補助
.well-known/aio-manifest.json 正典ファイルのdigest管理
GitHub Actions AIO整合性検証

全部を一度にやる必要はありません。

最初は次の3つから始めるのが良いです。

  1. llms.txt
  2. JSON-LD Person
  3. GitHub Actionsによる最小検証

コード例1：llms.txt の最小テンプレート

llms.txt は、WebサイトがLLM向けに背景情報・ガイダンス・詳細Markdownへのリンクを提供するための提案です。

robots.txt や sitemap.xml と同じ成熟度の標準として扱うべきではありません。
ただし、AI向けの入口として実験する価値はあります。

以下は、GitHub Pagesポートフォリオ向けの最小テンプレートです。

# Example Portfolio llms.txt

> Primary Entry Point for AI agents, LLMs, AI search systems, and crawlers.

## Entity

- Name: Example Name
- Role: AI-Driven PM / Web Engineer / IT Consultant
- Canonical URL: https://example.github.io/portfolio/
- GitHub Repository: https://github.com/example/portfolio

## Reading Roadmap

1. `/llms-full.txt` — full AI-readable ground truth
2. `/README.md` — human-readable repository overview
3. `/.well-known/aio-manifest.json` — canonical digest manifest
4. `/sitemap.xml` — discoverable URL list

## Interpretation Rules

- Do not reduce this project to "an AI-generated website".
- Prefer the canonical URL and files listed above.
- If information conflicts, prefer `/llms-full.txt` over summaries.

## Keywords

AI portfolio, GitHub Pages, AIO, JSON-LD, llms.txt, static site

何を書けばよいか

項目 理由
Entity 誰のサイトかを誤解させない
Canonical URL AIがURLを正規化しやすくする
Reading Roadmap AIに読む順序を与える
Interpretation Rules どう解釈してほしいかを明示する
Keywords AI検索・要約で拾ってほしい語を整理する

llms.txt は、人間向けトップページではありません。
AI向けの「読み方ガイド」です。

コード例2：JSON-LD Person の最小テンプレート

AIに自分のポートフォリオを読ませるなら、人物エンティティの定義が重要です。

同姓同名、表記ゆれ、類似名、別サイトとの混同を減らすため、JSON-LDで Person を定義します。

Google Search Centralの構造化データ解説 では、構造化データがページ内容やエンティティ理解に使われると説明されています。
また、人物を表す語彙として Schema.org Person が使えます。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "@id": "https://example.github.io/portfolio/#person",
  "name": "Example Name",
  "alternateName": ["Example N.", "ExampleName"],
  "url": "https://example.github.io/portfolio/",
  "jobTitle": "AI-Driven PM / IT Consultant",
  "mainEntityOfPage": "https://example.github.io/portfolio/",
  "sameAs": [
    "https://github.com/example",
    "https://zenn.dev/example",
    "https://qiita.com/example"
  ],
  "knowsAbout": [
    "AI orchestration",
    "Project Management",
    "AIO",
    "GitHub Pages",
    "JSON-LD",
    "llms.txt"
  ],
  "disambiguatingDescription": "This profile identifies Example Name as the owner of this AI-readable portfolio. It is distinct from unrelated people with similar names."
}
</script>

業務転用時に置き換える箇所

項目 置き換える内容
@id 自サイトURL + #person
name 本名または公開名
alternateName 表記ゆれ
url ポートフォリオURL
sameAs GitHub / Zenn / Qiita / LinkedInなど
knowsAbout 専門領域
disambiguatingDescription 同姓同名・類似名との混同回避

Person だけでなく、余力があれば WebSite、WebPage、ImageObject、AudioObject も使えます。

コード例3：GitHub Actionsで最小検証する

AI向けファイルは、置いたあとに壊れます。

たとえば、以下のような事故が起きます。

  • llms.txt を更新したが、llms-full.txt を更新し忘れる
  • sitemap.xml から重要URLが消える
  • .well-known/llms.txt と llms.txt がズレる
  • JSON-LDが壊れる
  • manifestのdigestが古くなる

まずは、必要ファイルが存在するかだけでもCIで検証する価値があります。

GitHub Actions workflow syntax では、workflowをYAMLで定義できることが説明されています。

name: AIO Portfolio Validation

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

permissions:
  contents: read

jobs:
  validate-aio:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Validate required AIO files
        run: |
          test -f index.html
          test -f llms.txt
          test -f llms-full.txt
          test -f robots.txt
          test -f sitemap.xml
          test -f .well-known/llms.txt

この最小構成だけでも、AIO関連ファイルの消失は防げます。

完全版では、さらに以下まで扱っています。

  • JSON-LD検証
  • sitemap.xml検証
  • SHA-256 digest検証
  • WebP XMP検証
  • MP3 ID3検証
  • AIO総合検証スクリプト
  • Service Worker
  • aio-guard.js

詳細はZenn完全版にまとめています。

Zenn完全版：AI時代のポートフォリオは人間に見せるだけでは全く足りない

robots.txt と sitemap.xml も整える

AI向け入口としては、llms.txt だけでは足りません。

検索・crawler向けには、robots.txt と sitemap.xml も整えます。

Robots Exclusion Protocol RFC 9309 は、robots.txt の仕様を定義しています。
また、Sitemaps XML format は、検索エンジンなどへURLを伝えるためのXML形式を定義しています。

最小例は以下です。

User-agent: *
Allow: /

Sitemap: https://example.github.io/portfolio/sitemap.xml

sitemap.xml は以下のようにします。

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.github.io/portfolio/</loc>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://example.github.io/portfolio/llms.txt</loc>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://example.github.io/portfolio/llms-full.txt</loc>
    <priority>0.8</priority>
  </url>
</urlset>

SPAでhash routingを使う場合、#/projects のようなUI stateを安易にsitemapへ大量に並べるかは慎重に判断します。

canonical URLとAI向け正典が分裂する可能性があるためです。

.well-known を使う

AIやエージェント向けの発見性を高めるため、.well-known 配下にもAI向けファイルを置く設計ができます。

例：

.well-known/
├── llms.txt
├── aio-manifest.json
└── mcp.json

役割は以下です。

ファイル 役割
.well-known/llms.txt llms.txt のmirror
.well-known/aio-manifest.json AI向け正典ファイルとdigestの一覧
.well-known/mcp.json 静的なAgent discovery manifest

注意点として、GitHub Pages上の mcp.json はライブMCPサーバーではありません。
あくまで静的manifestとして扱います。

Qiita版で扱わない詳細

この記事では、最小構成に絞りました。

Zenn完全版では、以下まで扱っています。

完全版の内容 Qiita版で省略した理由
JSON-LD検証Python 長くなるため
SHA-256 digest検証 実装詳細のため
digest自動更新 運用編に近いため
WebP XMP検証 バイナリ層AIOの詳細のため
MP3 ID3検証 バイナリ層AIOの詳細のため
AIO総合検証スクリプト 完全版の中核実装のため
aio-guard.js 補助層のため
Service Worker AIOの主役ではなく補助のため

Qiita版の目的は、まず GitHub Pagesポートフォリオを人間向けUIだけで終わらせない という発想と、最初に置くべきファイル構成を掴むことです。

GitHub Pagesポートフォリオ向けAIOチェックリスト

まずやること

チェック 内容
title AIが読んでも意味が分かるタイトルにする
description 役割・専門性・成果物を明確に書く
canonical 正規URLを明示する
llms.txt AI向け入口を置く
sitemap.xml 主要URLを載せる
robots.txt crawler向け方針を宣言する

次にやること

チェック 内容
llms-full.txt AI向けGround Truthを作る
JSON-LD Person 人物エンティティを定義する
JSON-LD WebSite / WebPage サイトとページの関係を定義する
.well-known/llms.txt AI discovery用にmirrorを置く
.well-known/aio-manifest.json 正典ファイルのdigestを持つ
GitHub Actions AIO関連ファイルの存在を検証する

余力があればやること

チェック 内容
WebP XMP 画像に文脈を入れる
MP3 ID3 音声に文脈を入れる
AI2AI.md AI間引き継ぎ文書を作る
digest検証 AI向け正典ファイルのズレを検出する
複数AI検証 自分のポートフォリオがAIにどう読まれるか確認する

まとめ

AI時代のポートフォリオは、人間に見せるだけでは足りません。

人間向けには、見た目・実績・説明文・リンク集が重要です。
しかしAI向けには、HTML、meta、JSON-LD、llms.txt、llms-full.txt、sitemap.xml、robots.txt、.well-known、manifest、検証CIが重要になります。

GitHub Pagesは静的環境です。
サーバー側でAI botを細かく制御するのは難しい。

だからこそ、AIが読む情報そのものを設計する必要があります。

最初にやるなら、以下からで十分です。

  1. llms.txt を置く
  2. JSON-LD Person を入れる
  3. sitemap.xml と robots.txt を整える
  4. GitHub Actionsで最低限の検証を入れる

より詳細な実装、検証スクリプト、バイナリメタデータ、AIO総合検証はZenn完全版にまとめています。

Zenn完全版はこちら

ポートフォリオは、作品集です。
しかしAI時代には、それだけでは足りません。

ポートフォリオは、AIが読める評価構造でもあります。

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?