A SOLO Skill that forces AI to read and write file-level .ai/ mirrors. Documentation-first coding plus cross-session agent memory so resume work does not start from zero.
| Pain Point | Why Plans Fail | How File Guardian Fixes It |
|---|---|---|
| AI breaks global styles when editing a Button | Plan only says "page has a button", doesn't constrain Button.tsx | File-level doc forces AI to read .ai/src/components/Button.md, knows it depends on theme.css |
| AI "fixes a bug" with hallucinated code | Plan was written at project start, AI ignores it during bug fixes | HARD-GATE forces documenting bug cause and fix plan before touching code |
| 3 months later, no idea why AI wrote code that way | Plan buried deep in folders, impossible to find | Mirrored structure — code path = doc path, always in sync |
| New session / resume agent forgets prior work | Chat is gone; only code remains | Mandatory READ of PROJECT_CONTEXT + file mirrors; Open Threads for unfinished plans |
.ai/ becomes a write-only dump nobody uses |
Agents only append logs | Read-to-act + write-for-next-reader rules; dense Decisions, not diaries |
| Dimension | Plan/Spec | File Guardian |
|---|---|---|
| Granularity | Project / Feature level | File level — every .tsx/.ts/.css gets its own doc |
| Location | Separate docs/ folder | Mirrored — src/components/Button.tsx maps to .ai/src/components/Button.md |
| Enforcement | "Please refer to design doc" (ignorable) | HARD-GATE — AI cannot modify code without reading doc first |
| Sync | Written once at project start, never updated | Forced sync — doc must be updated before code changes |
| Lifecycle | Project kickoff only | Full lifecycle — enforced on every single change |
| Memory | None across sessions | .ai/ is the handoff — resume reads Open Threads + Decisions first |
| Mode | Job |
|---|---|
| READ | Current agent reconstructs constraints, past decisions, open work |
| WRITE | Leave a handoff the next agent can act on (not a tool-call diary) |
If agents only write and never read, the folder is pure waste.
Code: AI Docs:
src/ .ai/src/
├── components/ ├── components/
│ ├── Button.tsx → │ ├── Button.md
│ └── Card.tsx → │ └── Card.md
├── utils/ ├── utils/
│ ├── format.ts → │ ├── format.md
│ └── validate.ts → │ └── validate.md
└── features/ └── features/
└── pricing/ └── pricing/
├── Calculator.tsx → ├── Calculator.md
└── utils.ts → └── utils.md
.ai/PROJECT_CONTEXT.md (Global project context)
Why .ai/:
- Hidden directory (
.prefix) — won't clutter your file explorer - Unique name — won't conflict with
docs/,doc/,documentation/ - Self-explanatory — clearly indicates AI constraint docs
You: Fix Button.tsx
AI: Creates .ai/src/components/Button.md (only this one, ignores other files)
Best for: 200k+ line codebases. Zero overhead — docs created only for files you actually use.
Trigger phrases:
- "Initialize all AI docs"
- "Full init File Guardian"
- "Create doc mirror for all files"
You: Initialize all AI docs
AI: Detected 482 files, processing in 25 batches...
[Batch 1/25] ✓
[Batch 2/25] ✓
...
All done!
Best for: When you want complete documentation upfront. Higher initial token cost, zero ongoing overhead.
Copy file-guardian/ to your SOLO skills directory:
# Typical paths
~/.solo/skills/file-guardian/
# or
/data/user/skills/file-guardian/Progressive (recommended):
You: Fix Button.tsx
AI: Auto-creates .ai/ directory and Button.md, then modifies code
Full initialization:
You: Initialize all AI docs
AI: Batch-creates .md docs for all files
Modify code:
You: Add loading state to Button
AI: Read .ai/Button.md → Update doc → Show for confirmation → Modify code → Sync doc
Fix bug:
You: Button click not working
AI: Read doc → Record bug cause and fix plan in doc → You confirm → Fix → Sync
Create new file:
You: Create a price calculator
AI: Create .ai/PriceCalculator.md (design doc) → You confirm → Write code
Each .ai/{path}/{file}.md contains:
# FileName
## Purpose (one sentence)
"A price calculator that takes quantity and unit price, auto-calculates total with discounts"
## What It Does
Detailed feature description
## Public API
| Name | Type | Description |
## Dependencies
- Internal: ./path/to/file — why
- External: package-name — why
## Open Threads / Resume Context
- Status / Intent / Next steps (empty when idle; primary input when resuming)
## Agent Decisions / Thoughts
- **{DATE} {AUTHOR}:** Durable *why* / trade-offs / rejected alternatives (not a play-by-play)
## Important Notes / NEVER Change
- Critical constraint 1
- Critical constraint 2
## Bug Fixes
| Date | Bug | Cause | Fix |
## Change History
| Date | Change | Author | ← one line per meaningful shipPROJECT_CONTEXT.md also has Current Work for project-level resume orientation.
NO DOC → NO WORK
NO READ → NO CODE (when a mirror already exists)
- Resume / multi-file? → Read
PROJECT_CONTEXT.mdfirst - Check
.ai/exists? → Create if not - Check file's
.mdexists? → Create FIRST if not - Read the doc and apply constraints / open threads
- Update doc with planned changes
- Get user confirmation
- Modify code
- Sync doc (clear or rewrite Open Threads; write for the next reader)
file-guardian/
├── SKILL.md # Main skill file
├── README.md # This file
├── rules/
│ ├── edge-cases.md # 9 edge case handlers
│ └── initialization.md # Initialization guide
└── templates/
├── file-doc.md # Single file doc template
└── project-context.md # Project-level doc template
Before (Plan approach):
You: Fix the Button click bug
AI: OK (directly modifies code, might fix it, might break it)
After (File Guardian):
You: Fix the Button click bug
AI:
[Reads .ai/src/components/Button.md]
"Per doc: Button uses theme.css, onClick must be bound to button element.
📄 Bug Fix Record:
- Problem: onClick bound to div
- Fix: Move to button element
- Impact: Current file only
Confirm to proceed?"
You: Confirm
AI: [Fix, verify, sync doc]
Resume (memory path):
You: continue the overnight stuck-receipt work
AI:
[Reads .ai/PROJECT_CONTEXT.md → Current Work]
[Reads .ai/src/lib/receiptWorkflow.md → Open Threads + Decisions]
"From .ai/: BACKGROUND_STALE_MS already lowered to 3 min; next was expand enqueue for mid-flight statuses.
Continuing that plan rather than redesigning..."
- Resume / read-to-act path so
.ai/is used as agent memory - Open Threads section for mid-task handoff
- Auto-sync detection (warn when code changes without doc update)
- More languages (Python, Go, Rust)
- Doc change diff display
- VSCode extension
MIT
强制 AI 先读后写 文件级 .ai/ 镜像的 SOLO Skill。文档优先写代码，并把 .ai/ 当作 跨会话 Agent 记忆，避免 resume 时从零开始。
| 被坑场景 | 为什么 Plan 没用 | File Guardian 怎么解决 |
|---|---|---|
| 让 AI 改个 Button 组件，结果把全局样式搞崩了 | Plan 只描述"页面有按钮"，不约束 Button.tsx 具体怎么写 | 文件级文档强制 AI 读 .ai/src/components/Button.md，知道它依赖 theme.css |
| AI 说"修复了 bug"，其实是幻觉编答案 | Plan 是项目初期写的，修 bug 时 AI 不会去看 | HARD-GATE强制修 bug 前先写修复方案到文档 |
| 三个月后看代码，不知道 AI 为什么这么写 | Plan 埋在文件夹深处，找不到了 | 镜像结构，代码在哪文档就在哪，永远同步 |
| 新会话 / resume 忘了上次做到哪 | 聊天记录没了，只剩代码 | 强制先读 PROJECT_CONTEXT + 文件镜像；Open Threads 记未完成计划 |
.ai/ 变成只写不用的流水账 |
Agent 只会追加日志 | 读了再干活 + 写给下一个读者；Decision 要短，不要日记 |
| 维度 | Plan/Spec | File Guardian |
|---|---|---|
| 粒度 | 项目级/功能级 | 文件级 — 每个 .tsx/.ts/.css 都有自己的文档 |
| 位置 | 单独的 docs/ 或根目录 | 镜像结构 — src/components/Button.tsx 对应 .ai/src/components/Button.md |
| 强制力 | "请参考设计文档"（可忽略） | HARD-GATE — 强制 AI 先读文档，不读不能改 |
| 同步 | 项目初期写一次，后期不同步 | 强制同步 — 改代码前必须先更新文档 |
| 适用阶段 | 项目启动期 | 全生命周期 — 每次修改都生效 |
| 记忆 | 跨会话无记忆 | .ai/ 即交接 — resume 先读 Open Threads + Decisions |
| 模式 | 作用 |
|---|---|
| 读 | 当前 Agent 恢复约束、历史决策、未完成工作 |
| 写 | 给 下一个 Agent 留下可执行交接（不是工具调用日记） |
只写不读 = 纯浪费。
代码：src/components/Button.tsx
文档：.ai/src/components/Button.md
代码：src/utils/format.ts
文档：.ai/src/utils/format.md
为什么 .ai/：
- 隐藏目录（
.开头），不会和普通文件夹混淆 - 独特命名，不会和
docs/冲突 - 明确表示这是 AI 约束文档
你：帮我改 Button.tsx
AI：创建 .ai/src/components/Button.md（仅此一个，其他文件不处理）
适合：20万行代码大项目，用哪个创哪个，零 overhead。
触发语：
- "给我初始化所有 AI 文档"
- "全量初始化 File Guardian"
- "给所有文件创建文档镜像"
你：给我初始化所有 AI 文档
AI：扫描到 482 个文件，分 25 批处理...
[第 1/25 批] ✓
[第 2/25 批] ✓
...
全部完成！
适合：你想一次性全搞定，愿意付 token 成本换完整文档。
将 file-guardian 目录复制到你的 SOLO skills 目录：
# 通常路径
~/.solo/skills/file-guardian/
# 或
/data/user/skills/file-guardian/渐进式（推荐）：
你：帮我改 Button.tsx
AI：自动创建 .ai/ 目录和 Button.md，然后修改代码
全量初始化：
你：给我初始化所有 AI 文档
AI：批量创建所有文件的 .md 文档
修改代码：
你：给 Button 加 loading 状态
AI：读 .ai/Button.md → 更新文档 → 展示确认 → 改代码 → 同步文档
修复 bug：
你：Button 点击没反应
AI：读文档 → 在文档记录 bug 原因和修复方案 → 你确认 → 修复 → 同步
创建新文件：
你：创建价格计算器
AI：先创建 .ai/PriceCalculator.md（设计文档）→ 你确认 → 写代码
每个 .ai/{path}/{file}.md 包含：
# FileName
## Purpose（一句话人话）
"这个是价格计算器，用户输入数量和单价，自动计算总价"
## What It Does
详细功能描述
## Public API
| Name | Type | Description |
## Dependencies
- Internal: ./path/to/file — why
- External: package-name — why
## Open Threads / Resume Context
- Status / Intent / Next steps（空闲时留空；resume 时优先读这里）
## Agent Decisions / Thoughts
- **{DATE} {AUTHOR}:** 耐用的 *为什么* / 权衡 / 被否方案（不是逐步操作日志）
## Important Notes / NEVER Change
- 关键约束1
- 关键约束2
## Bug Fixes
| Date | Bug | Cause | Fix |
## Change History
| Date | Change | Author | ← 每次有意义的改动一行即可PROJECT_CONTEXT.md 另有 Current Work，用于项目级 resume 定向。
NO DOC → NO WORK
NO READ → NO CODE（已有镜像时）
- Resume / 多文件？→ 先读
PROJECT_CONTEXT.md - 检查
.ai/存在？不存在则创建 - 检查文件对应的
.md存在？不存在则先创建 - 完整读文档，应用约束 / Open Threads
- 更新文档（计划变更）
- 用户确认
- 修改代码
- 同步文档（清理或改写 Open Threads；写给下一个读者）
file-guardian/
├── SKILL.md # 主技能文件
├── README.md # 本文件
├── rules/
│ ├── edge-cases.md # 9个边缘情况处理
│ └── initialization.md # 初始化指南
└── templates/
├── file-doc.md # 单文件文档模板
└── project-context.md # 项目级文档模板
以前（Plan 方式）：
你：帮我修 Button 的点击 bug
AI：好的（直接改代码，可能修对，可能修错）
现在（File Guardian）：
你：帮我修 Button 的点击 bug
AI：
[读取 .ai/src/components/Button.md]
"根据文档，Button 使用 theme.css，onClick 必须绑定到 button 元素。
📄 Bug Fix 记录：
- 问题：onClick 绑定到了 div
- 修复：移到 button 元素
- 影响：仅当前文件
确认后实施修复。"
你：可以
AI：[修复，验证，同步文档]
- Resume / 先读后写，把
.ai/真正当成 Agent 记忆 - Open Threads 支持中断任务交接
- 文档自动同步检测（代码改了提醒更新文档）
- 支持更多语言（Python、Go、Rust）
- 文档变更 diff 展示
- VSCode 插件支持
MIT