path: root/doc/Specifications.md

# Specifications.md

# たかしの記録 — 要求仕様書

## 1. 文書目的

本書は、個人Webサイト「たかしの記録」の利用者視点・コンテンツ視点での要求仕様を定義する。

本書では「何を提供するサイトか」「誰がどのように読むか」「どの情報をどのように見せるか」を定義し、具体的なZola/Tera/SCSS実装方法は `Design.md` に委ねる。

---

## 2. サイト概要

### 2.1 サイト名

**たかしの記録**

### 2.2 サイトの目的

本サイトは、運営者が日頃考えたこと・感じたこと・調べたことを記録し、作成したソフトウェアとともに長期的に保存・公開する個人アーカイブである。

主な用途は次のとおり。

- 日々考えたことや感じたことの記録
- 読書を通じて考えたことの記録
- 技術調査・技術メモの公開
- 長文記事・考察の公開
- 作成したソフトウェアの紹介
- ソフトウェア制作の背景・過程・設計意図の記録
- ソフトウェアに関連する技術記事との相互参照

### 2.3 主な対象分野

Notesでは特定分野に限定せず、少なくとも以下を扱う。

- 情報工学・ソフトウェア
- 論理学
- マルクス・資本論・政治経済
- 地球環境
- 読書を通じた考察
- 上記にまたがる複合的なテーマ

分類は固定カテゴリではなくタグを基本とし、分野横断の記事を許容する。

### 2.4 想定読者

- 運営者本人
- ソフトウェアエンジニア
- 技術分野に関心のある一般読者
- 学生
- 個々の記事テーマに関心のある一般人

専門読者だけに限定せず、記事冒頭で主題を把握できることを重視する。

### 2.5 更新頻度

通常は **2〜3か月に1〜2回程度** を想定する。

更新頻度を競うニュースサイトやSNSではなく、長期間残るアーカイブとして設計する。

---

## 3. サイトの基本コンセプト

### 3.1 中心コンテンツ

サイトの主役は以下の2つとする。

1. **Notes**
2. **Software**

HomeとAboutは、この2つへの入口・補助情報として扱う。

### 3.2 デザインコンセプト

デザインは **Minimal Editorial Archive** を基本とする。

方向性は以下。

- 文章とリンクを主役にする
- 装飾を抑える
- 罫線・余白・タイポグラフィで情報階層を表現する
- カードUIを乱用しない
- 画像を主役にしない
- 技術者向けダッシュボード風・SaaSランディングページ風にしない
- 長文を落ち着いて読める
- 更新間隔が長くても「止まったサイト」に見えにくい
- Gwern.netの長文アーカイブ性とSimon Willison's Weblogの実用的な情報構造を参考にする

### 3.3 基本画面構造

全画面の基本構造は以下。

- 小さなHeader
- Main content
- 小さなFooter

Header/Footerは本文より目立たせず、高さも必要以上に取らない。

Sidebarは使用しない。

---

## 4. 情報アーキテクチャ

### 4.1 グローバル構成

トップレベルは以下を基本とする。

- `/` — Home
- `/notes/` — Notes一覧
- `/software/` — Software一覧
- `/about/` — About
- `/tags/` — タグ一覧
- `/tags/<tag>/` — タグ別Notes等の一覧

### 4.2 グローバルナビゲーション

Headerに以下を表示する。

- Home
- Notes
- Software
- About

Source/cgitへのリンクはグローバルナビゲーションには常設せず、Software内で案内する。

---

## 5. Home仕様

### 5.1 役割

Homeはサイト全体の入口・索引として機能する。

ポートフォリオ用の大きなHero、自己宣伝CTA、プロフィール写真などは必須としない。

### 5.2 表示内容

以下の順序を基本とする。

1. 短い説明文
2. 最近のNotes
3. Software
4. サイトについての短い説明
5. Aboutへの導線

サイト名はHeaderに表示されるため、Home本文では重複表示しない。

### 5.3 トップ説明文

初期文言：

> 日々考えたこととか思ったことを記録します

将来文言を修正できること。

### 5.4 最近のNotes

初期表示件数は **5件** とする。

各項目には以下を表示する。

- 公開日
- タイトル
- 必要に応じ短いdescription

Homeでは情報量を抑え、本文を直接大量表示しない。

### 5.5 Software

初期表示件数は **4件** とする。

Homeでは原則としてSoftware名を中心に表示する。

---

## 6. Notes仕様

### 6.1 Notesの定義

文章として残したい内容は原則としてNotesとして扱う。

技術メモ、読書記録、調査、考察、論考を別々のコンテンツ型へ過度に分割しない。

### 6.2 Notes一覧

Notes一覧は **年別アーカイブ** とする。

例：

- 2026
  - 08-21 記事タイトル
  - 05-03 記事タイトル
- 2025
  - ...

年は新しい順、各年内も原則として公開日の新しい順に表示する。

### 6.3 Notes一覧に表示する情報

- 公開日
- タイトル
- タグ
- 必要に応じdescription

タグはNotes一覧およびタグ一覧で表示する。

### 6.4 Note詳細

Note詳細では以下を表示する。

- タイトル
- 公開日
- 更新日（存在する場合）
- 目次
- 本文
- 脚注
- 参考文献
- 関連Software（設定されている場合）
- 前後の記事導線は必須としない

タグはNote詳細の主要表示項目にしない。

### 6.5 目次

Note詳細では **目次を常時表示**する。

Sidebarは使わないため、本文冒頭付近にインラインで配置する。

見出しが存在しない場合は空の目次領域を表示しない。

### 6.6 脚注

Markdown/Zola標準機能による脚注を日常的に利用できること。

脚注の見た目を本文と一貫させる。

### 6.7 参考文献

長文記事の末尾にReferences/参考文献セクションを設けられること。

参考文献は通常のMarkdownで記述可能とし、共通の見た目を持つ。

### 6.8 公開日と更新日

- 公開日は必須
- 更新日は任意
- 更新日が存在する場合は公開日とともに表示する

### 6.9 記事の成熟度

Draft / Note / Essay 等の成熟度・状態ラベルは導入しない。

Zola内部のdraft機能は公開制御に使用してよいが、利用者向けの成熟度表示は行わない。

---

## 7. Tags仕様

### 7.1 分類方針

初期実装ではカテゴリを設けず、**tagsのみ**を使用する。

### 7.2 タグの目的

- 分野横断の記事を柔軟に分類する
- 同じテーマの記事を探せるようにする
- 固定カテゴリ階層を避ける

### 7.3 想定タグ例

- 情報工学
- 論理学
- 資本論
- 政治経済
- 地球環境
- AI
- LLM
- 読書
- Windows
- Git

タグ語彙はコンテンツ追加に応じて増やす。

---

## 8. Software仕様

### 8.1 役割

Softwareは作成したソフトウェアを人間向けに説明する場所とする。

ソースコードそのものの閲覧・履歴表示はcgitへ委ねる。

### 8.2 Software一覧

一覧では情報量を抑え、**Software名を主表示**とする。

必要に応じ短いdescriptionを添えてよいが、画像や大量のmetadataは表示しない。

### 8.3 Software詳細

以下の情報を扱えること。

- Software名
- 概要
- 作成した背景・目的
- 開発・制作の過程
- 特徴
- 使用言語
- ライセンス
- Source（自前cgit）
- GitHub mirror（存在する場合）
- 関連Notes
- スクリーンショット（必要な場合のみ）

Implementation detailsは本文中で必要な範囲だけ記述し、固定項目として過剰に構造化しない。

### 8.4 Sourceの優先順位

ソースコードの正本は **自前cgit** とする。

Software詳細では以下の順で扱う。

1. Source — cgit
2. GitHub mirror — 当面維持

### 8.5 スクリーンショット

- Software一覧では表示しない
- Software詳細で必要な場合のみ表示する
- 画像が多くなり本文の可読性を損なわないようにする

---

## 9. NotesとSoftwareの関連付け

NotesとSoftwareは相互に関連付けられること。

例：

- Softwareから関連Notesへ
- Noteから関連Softwareへ

関連付けは明示的に管理し、単なるタグ一致だけで自動的に関連付けない。

---

## 10. About仕様

Aboutには以下を掲載する。

- 名前
- 一言プロフィール
- このサイトの目的
- 主な関心分野
- 連絡先

職務経歴書・詳細な履歴書としては設計しない。

---

## 11. Header仕様

### 11.1 表示内容

- サイト名「たかしの記録」
- Home
- Notes
- Software
- About
- Dark/Light theme切替（提供する場合）

### 11.2 レイアウト

- 高さを抑える
- サイト本文より主張しない
- DesktopとMobileの双方で簡潔に表示
- 必要でなければHamburger menuは使用しない

---

## 12. Footer仕様

Footerには最低限以下を表示する。

- Copyright
- RSS
- Mail

cgitリンクはSoftware側で扱う。

---

## 13. Typography仕様

### 13.1 本文

Sans-serifを使用する。

Web fontは外部取得せず、system font stackを使用する。

### 13.2 UI

Sans-serif + Monospaceを役割分担して使用する。

Monospaceは以下のような補助情報に使用できる。

- 日付
- metadata
- ラベル
- コード
- 技術的な短い補助情報

### 13.3 コード

system monospaceを使用する。

---

## 14. 色・テーマ仕様

### 14.1 Light theme

- 紙に近い暖かみのある明るい背景
- ほぼ黒の本文
- muted gray
- 薄い罫線
- 青をaccent/link色として使用

### 14.2 Dark theme

Dark modeに対応する。

- 真っ黒ではなく濃いgrayを基本
- 明るい本文
- muted gray
- dark border
- light themeと対応する青系accent

### 14.3 Accent

Accentは青系1色を基本とする。

具体的な色値はDesignで定義する。

---

## 15. リンク仕様

- 通常リンクは青
- 原則として下線を付け、リンクであることを明確にする
- Hoverでは色等を軽く変える
- 大きなアニメーションを付けない
- 外部リンクには `↗` 等の簡潔な外部リンク記号を表示する
- 外部アイコンライブラリは使用しない

---

## 16. Layout仕様

- Sidebarなし
- Main contentを中央付近に配置
- 長文は左右に十分な余白を確保
- 最大本文幅はDesign段階で具体値を定義
- Desktopでは広すぎない
- Mobileでは横スクロールを発生させない
- コードブロック等、必要な要素のみ内部横スクロールを許容

---

## 17. Motion仕様

Animationは原則使用しない。

以下も初期実装では不要。

- View Transition
- Parallax
- Scroll animation
- Fade-in animation
- Decorative motion

---

## 18. 画像仕様

- 画像は最小限
- Homeに装飾目的の大量画像を置かない
- Notesでは説明に必要な画像のみ
- Softwareでは詳細ページのみ
- 外部画像hotlinkを原則避ける
- 代替テキストを付与する

---

## 19. Feed仕様

以下を提供する。

- Atom
- RSS

HeaderまたはFooterから購読導線を用意する。

Feed autodiscoveryに対応する。

---

## 20. Search仕様

初期リリースではSearchを提供しない。

将来の記事数増加に応じて、Zolaの検索インデックス機能を第一候補として追加検討する。

---

## 21. Comments仕様

初期リリースではコメント機能を提供しない。

理由：

- 完全静的構成では保存先が存在しない
- 自前backendを追加すると現行セキュリティ境界が変化する
- 外部コメントサービスは外部依存・プライバシーの再検討が必要

将来機能として、以下を別途評価する。

- 自前軽量コメントbackend
- Gitベース方式
- 外部コメントサービス
- Mailによる感想受付

---

## 22. SNS共有仕様

初期リリースでは大きなSNS共有ボタン群を必須としない。

外部dependencyを追加せず、簡潔なテキストリンクまたはWeb Share API等だけで実現できる場合に追加を検討する。

サイトのEditorialデザインを損なわないことを優先する。

---

## 23. Analytics仕様

アクセス解析は導入しない。

- 外部Analytics scriptなし
- Tracking cookieなし
- Marketing trackerなし

Webサーバの運用ログはサーバ運用上のログであり、サイト機能としてのアクセス解析とは扱わない。

---

## 24. URL仕様

### 24.1 URL構造

- `/notes/<slug>/`
- `/software/<slug>/`
- `/tags/<slug>/`
- `/about/`

### 24.2 Slug

Content filename / slugは **英語ASCIIを基本**とする。

記事本文や表示タイトルは日本語でよい。

URLの安定性を優先し、公開後のslug変更は原則避ける。

---

## 25. 日本語・多言語仕様

- 表示言語は日本語のみ
- UI文言も日本語
- 初期設計では多言語対応を実装しない
- 多言語化のための不要なUIやselectorは設けない

---

## 26. Accessibility要求

最低限以下を満たす。

- Semantic HTML
- 適切なheading hierarchy
- Keyboard navigation
- Visible focus
- 十分な色contrast
- 画像alt
- Linkが色だけで判別不能にならない
- HTML/主要navigationはJavaScriptなしでも利用可能
- Theme切替機能がなくてもOS themeで十分読めること
- prefers-reduced-motionを尊重（原則motion自体を使用しない）

---

## 27. Performance要求

サイトは静的HTML/CSS/最小JSのみで成立すること。

- Backend runtime不要
- DB不要
- npm/Node.js不要
- 外部CDN不要
- Web font不要
- 大きなfrontend framework不要
- 初期表示に不要な画像を読み込まない
- JavaScriptが無効でも主要本文が読める

---

## 28. Security / Privacy要求

- npm package dependencyを使用しない
- Node.js runtimeを使用しない
- 外部themeを原則使用しない
- 外部JavaScript CDNを使用しない
- Inline JavaScriptを避ける
- `eval()` を使用しない
- 外部trackingを使用しない
- CSP `default-src 'self'` を中心とした厳格な設定と互換性を持つ
- Static Siteとして本番にserver-side codeを置かない
- Caddyは生成済み成果物のみを配信する

---

## 29. 技術基盤に関する制約

以下はDesignに委ねるが、要求上の前提とする。

- SSG: Zola
- Template: Tera
- Content: Markdown
- Style: SCSS
- Client JS: minimal vanilla JavaScript
- Production: Caddy static file server
- Build: Client PC
- Deployment: `public/` build artifactをVPSへ転送
- Git source管理とDeployは独立
- cgitをソースコード正本とする

---

## 30. 初期リリースの非目標

以下は初期リリースで実装しない。

- コメント
- Search
- CMS
- User login
- Database
- SSR
- SPA
- API backend
- WebSocket
- Analytics
- Frontend framework
- htmx
- Tailwind CSS
- npm/Node.js
- External theme
- Heavy animation
- Large image gallery
- Multilingual UI

---

## 31. 受入条件

初期リリースは以下を満たすこと。

- [ ] 「たかしの記録」というサイト名が表示される
- [ ] Home / Notes / Software / Aboutへ到達可能
- [ ] Homeに最近のNotes最大5件を表示
- [ ] HomeにSoftware最大4件を表示
- [ ] Notesが年別に表示される
- [ ] Notes一覧にタグが表示される
- [ ] Note詳細に公開日・更新日・目次・本文を表示できる
- [ ] 脚注を利用できる
- [ ] 参考文献を自然に表示できる
- [ ] Software一覧を画像なしの簡潔な一覧として表示
- [ ] Software詳細に背景・過程・言語・ライセンス・Source等を記載できる
- [ ] cgitをSource正本として案内できる
- [ ] GitHub mirrorを任意表示できる
- [ ] NoteとSoftwareを明示的に相互関連付けできる
- [ ] Aboutに名前・一言プロフィール・目的・関心分野・連絡先を表示できる
- [ ] Light/Dark双方で読める
- [ ] 外部リンクを視覚的に判別できる
- [ ] RSSとAtomを提供
- [ ] 404ページを提供
- [ ] Mobile/Desktop双方で利用可能
- [ ] JavaScriptなしでも主要コンテンツを閲覧可能
- [ ] 外部CDN・npm・Node.js・frontend frameworkを必要としない
- [ ] サイト全体が静的ファイルとして生成可能

---

## 32. 将来拡張

要件変更時に別途設計する。

- Search
- Comments
- SNS共有
- より高度な関連コンテンツ表示
- タグ数増加へのUI改善
- Page pagination
- 多言語
- 画像処理の高度化

初期実装で将来拡張のための複雑な抽象化を先行導入しない。