From 9c7d9f40a2f1f27c967405d78bca587e82b91615 Mon Sep 17 00:00:00 2001
From: clz <fadinglight9291117@126.com>
Date: Wed, 1 Jul 2026 18:13:30 +0800
Subject: [PATCH] docs: add AGENTS.md for note-writing conventions

---
 AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..683dc94
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,51 @@
+# AGENTS.md
+
+This is a personal Obsidian vault of **study notes** analyzing the OpenClaw
+(and occasionally OpenCode) source code. There is no build/test/lint/CI —
+it's markdown only. Notes are written in **Chinese (simplified)**; match
+that when adding or editing content.
+
+## Repo layout — two distinct note types, don't mix them up
+
+- Root `*.md` — deep technical/architecture notes (研究笔记): source-cited,
+  precise, written for the author's own understanding. Cite exact file
+  paths and line refs from the source repo.
+- `blog/*.md` — reader-facing "101" explainer articles (科普向), derived
+  from the same research but rewritten for an outside audience (problem →
+  intuition → source-backed example). Don't add deep-dive content here;
+  put it in a root note and link to it instead (see cross-links at the
+  bottom of `blog/skills-101.md` / `blog/rag-101.md` for the pattern).
+- Each of `README.md` (root) and `blog/README.md` is a **manual index**
+  listing every note with a 2-3 line summary. When adding a new note file,
+  add an entry to the matching README — this is easy to forget (two
+  existing notes, `agent-loop-notes.md` and `opencode-plan-mode.md`, are
+  currently missing from the root index).
+- `.obsidian/` is Obsidian's vault config (workspace layout, plugins) —
+  don't hand-edit `workspace.json`; it's UI state, not content.
+
+## Source of truth lives outside this repo
+
+This folder is a nested git repo (own history/remotes) living inside a
+checkout of the OpenClaw source at the parent directory
+(`/Users/clz/Code/openclaw`, one level up from here). That parent repo has
+its own `AGENTS.md`/`docs/` — notes here are written by reading *that*
+source, not by re-deriving architecture from prose.
+
+Some notes (e.g. `opencode-plan-mode.md`) instead study a **sibling repo**,
+referenced in the note as `../opencode` (i.e. `/Users/clz/Code/opencode`
+relative to this vault's parent). If a note cites a sibling repo, verify
+claims against that repo's actual source before editing/extending the note
+— don't trust the note's paraphrase alone.
+
+When writing or updating a note:
+- State which source repo/version the note is based on (existing notes
+  open with a blockquote like `> 基于 2026.6.2 版本源码，关键文件：...`
+  or `> 基于 sibling 仓库 ../opencode 源码实读`) — follow that convention.
+- Prefer citing concrete `file:line` references over paraphrased claims.
+
+## Git remotes
+
+Two remotes are configured and both are pushed to: `origin` (GitHub,
+`FadingLight9291117/openclaw-notes`) and `gitea` (private instance at
+`git.fadinglight.cn`). Don't assume only one remote — push to both if
+asked to publish, or ask which one if unclear.