id: principles title: Principles — why Fragment treats a note as shared structure scope: public updated: 2026-08-07 tags: - fragment - principles
Status: design principles — the rationale behind the Fragment format. Not a specification; these notes evolve with the format. Purpose: record why the format is shaped the way it is, so later decisions can be checked against the original reasoning.
Fragment treats each note as a small piece of shared structure, not just a block of text. YAML holds assumptions and boundaries; Markdown holds the story and the reasoning. Both humans and AI read the same page.
Fragment は、ノートを「ただの文章」ではなく、前提や境界線をふくむ小さな構造 として扱います。YAML に前提や配慮を、Markdown に本文や流れを書き、人と AI が 同じページを読む前提をつくります。
Fragment is less a note-taking app and more a small protocol for thinking. YAML captures who is speaking, from what perspective, and with which boundaries. Markdown carries the main narrative. Together they make it easier for humans and AI to share the same context.
1. One note = text + a small schema
本文（Markdown）＋前提の小さなスキーマ（YAML） として、1 つのノートを扱います。
A fragment isn't just a free-form page. At the top, and in small blocks, you can describe who is writing, for whom, and why this note exists. This structure stays small on purpose, so it feels like part of everyday writing rather than a separate configuration screen.
- YAML for author, intent, audience, and a few flags.
- Markdown for the main narrative, questions, and decisions.
- Both live on the same page, so the link between them is not lost.
2. Ethics as configuration, close to the text
倫理や配慮は、「離れたポリシー」ではなくノートのそばの設定値として扱います。
Many tools keep values and safety rules in distant policy documents. Fragment keeps them closer. With small Prism blocks you can say what to avoid, what to double-check, and how direct the tone should be when AI responds on this page.
- Describe tone — calm, direct, gentle — in YAML rather than leaving it implied.
- List the topics where you want extra care or a clear boundary.
- Let AI read these settings before it answers, not after something goes wrong.
3. Humans and AI share the same structure
人と AI が、同じ構造を読んで・同じノートに書き足すことを前提にします。
Instead of a private prompt document on one side and a separate note on the other, Fragment lets both live together. When the model replies, it can respect the same structure you use with colleagues, students, or your future self.
- One fragment can be read by you, your team, and an AI with the same context.
- Scene and Flow diagrams stay as text, so they are searchable and diffable.
- Over time the pages become a shared history rather than one-off conversations.
4. Calm over clever, everyday over spectacular
「すごい一発技」よりも、疲れている日でも開ける静かなページを優先します。
Fragment does not try to gamify thinking or flood you with suggestions. The aim is a page you can open on an ordinary day, leave one small fragment in, and trust that it will still make sense a week or a year later.
- Fewer badges and alerts, more readable pages.
- AI helps after you have written something, so your own voice stays visible.
- Structure can change later. Getting one honest note down is enough for today.
Origin and evolution
These principles were first written as the manifesto of a notebook application (2025). The application converged, but the principles held up better than the product framing: what survived is the format — one page that carries text and explicit structure together — now specified in Fragment format.
The same ideas later appeared in how Fragment Practice operates: structured, Git-versioned documents as the canonical record of decisions — one fact in one place, plain text that people, AI, and version control read alike. How much of that is inheritance and how much is convergence is a present-day reading, not a recorded causal chain. What the history does show is that these principles were written first (2025), and that they return here as the rationale for a format rather than a product.
この原則は、もともとノートアプリの manifesto（2025）として書かれました。 アプリケーションは収束しましたが、原則は製品よりも長持ちしました。残ったのは 「本文と明示的な構造を 1 ページで持ち運ぶ」フォーマットです。同じ考え方は、 のちに Fragment Practice の運用 —— 構造化された Git 管理の文書を判断の正本と する —— にも現れています。どこまでが継承でどこからが収斂かは現在からの解釈 ですが、原則が先に書かれたこと、そしていま製品ではなくフォーマットの設計根拠 としてここへ戻っていることは、履歴から確認できます。
What to do with this
You don't have to agree with every word. If anything here resonates, the simplest way to try it is to write one fragment with a small YAML block — a short note, plus a few lines about how you want it read.
このページは立派な約束というより、「こういう方向で育てていきたい」というメモです。 もし少しでもしっくりくるところがあれば、1 件の fragment に小さな YAML を添える ところから試してみてください。
関連する資料は Fragment format、 Prism Protocol、 How to write a clear Fragment にあります。