Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (71 loc) · 5.84 KB

AGENTS.md

File metadata and controls

104 lines (71 loc) · 5.84 KB
Raw

AGENTS.md — Coding Vault 规范层（多 Agent 唯一共识源）

RFC 2119 声明：本规范 MUST / MUST NOT / SHOULD / MAY 遵从 RFC 2119。所有进入本知识库（Vault）的 AI Agent MUST 遵循本规范。

1. 加载与继承顺序

  1. 先读全局规则：Agent MUST 首先读取 ~/.claude/CLAUDE.md（本机环境事实、反奉承哲学与防泄露守卫；若该文件不存在——例如模板包接收者环境——则跳过此步）。
  2. 后读 Vault 规则：Agent MUST 随后加载本文件。
  3. 开工必读：任何知识产出/重构/设计前，MUST 先加载 〔你的个人画像〕 与 〔你的领域通用规范〕。

记号约定：凡 〔…〕 形态的路径，表示"该文件需按你的领域自建"——在本库中它们是实文件；在公开模板包中是占位（质量门禁自动豁免其 wikilink）。

  1. 单源一致：CLAUDE.md/GEMINI.md/.cursorrules/.windsurfrules/CONVENTIONS.md 均为指向本文件的符号链接（模板包中为字节一致的内容副本），MUST NOT 覆写为独立实体，修改 MUST 仅作用于本文件（副本形态由 post-write-sync-agents.sh 同步）。

2. Vault 定位与作用域

  1. 核心定位：{{VAULT_ROOT}} 是知识沉淀与规范速查的 LLM-Native 知识库。
  2. 职责边界：本 Vault IS 知识资产与规范源；IS NOT 项目运行代码仓库（代码统一在 {{CODE_ROOT}}\）。
  3. 引用格式：库内引用 MUST 用 Wikilink（[[01-Rules/CODING-UNIVERSAL]]）；跨库引用项目 MUST 标注绝对路径（{{CODE_ROOT}}\{project}）。

3. 目录架构

区 目录 职责
导航 00-MOC/ 全库导航与聚合枢纽
规范 01-Rules/ 跨语言铁律、Agent 行为、环境事实
学科 02-Fundamentals/ OS/网络/体系结构/编译原理（壳*）
学科 03-Languages/{LANG}/ 语言双版本规范（STANDARDS+CHEATSHEET）
学科 04-Systems/ MySQL/Redis/Kafka/分布式/云原生（壳*）
学科 05-Tools/ 工具用法与配置（Claude Code/MCP/Obsidian）
摄入 06-Sources/{Type}/ 书/视频/文章/论文研读（壳*）
摄入 07-Academics/ 课程实验与毕设（壳*）
摄入 08-Projects/{PROJECT}/ 项目约束、ADR、Post-mortem
摄入 09-Career/ 面试高频考点与答辩复盘
过程 10-Daily/ 个人日志，MUST NOT 堆积未加工规则
过程 11-Agents/ Agent 审计日志（review-log.md 索引 + logs/YYYY-MM.md 按月分片）
流程 99-Inbox/ 摄取 Landing Zone（TTL 内流转）
工具 Templates//skills//scripts/ 模板/技能资产/代码，不入检索

* 科目壳 = 内容 <3 篇的意图清单，不建 MOC、不入脚本映射、不设门禁（[[01-Rules/VAULT-STRUCTURE]] §2）。

完整目录职责、壳目录策略、内容归属裁决表、Frontmatter schema、双版本制、三层记忆分工细则，MUST 遵循唯一宿主 [[01-Rules/VAULT-STRUCTURE]]。

4. Frontmatter 与双版本制

  1. 正式笔记（草稿/MOC 除外）MUST 含标准 YAML frontmatter；字段与标签空间见 [[01-Rules/VAULT-STRUCTURE]] §4。
  2. 语言双版本：STANDARDS 为主真值源；CHEATSHEET 由 Agent 单向浓缩（严禁 Drift）、章节 1:1 对齐；见 [[01-Rules/VAULT-STRUCTURE]] §5。

5. 通用开发规范与开发者画像

完整 13 条基线见 〔你的个人画像〕、〔你的领域通用规范〕。要点：拒绝奉承、命名表意图（YAGNI）、注释讲为什么、离开时更干净、错误显式处理（领域专题规范）、结构化并发（领域专题规范）、验证后下结论。

补充规范：Python 打包与模块入口（工具链规范）、文档治理与入口拆分（[[01-Rules/DOC-GOVERNANCE]]）、子 Agent 定义审计（[[01-Rules/AGENT-AUDIT-CHECKLIST]]）。

6. 新项目初始化与防泄露

完整规则见 [[01-Rules/GIT-CONVENTIONS]]、[[01-Rules/AGENT-CONDUCT]]。要点：新项目 MUST 自动初始化（或 pwsh scripts/bootstrap.ps1）；密钥 MUST 入 .gitignore；提交前过密钥扫描；MUST NOT git commit --no-verify。

7. 对话即沉淀（Karpathy 模式）

标准见 [[01-Rules/INGESTION-WORKFLOW]]。要点：自主查库对齐 / 质量自审 / 经验沉淀（[[01-Rules/AGENT-CONDUCT]] §9）；沉淀经 save_inbox_draft 落 99-Inbox/，定稿后由 vault-inbox-consolidate 归位并删除原件。

8. 自检与维护

  1. 符号链接/内容副本：每月或环境变动后 MUST 验证 5 入口与 AGENTS.md 一致（本库为符号链接；模板包为内容副本，由 Check 5 校验）。
  2. 体积红线：本文件 SHOULD ~5KB，MUST NOT >10,240 B；超限 MUST 拆细则至 01-Rules/。
  3. Git 审阅：改规范前 SHOULD git log -n 5；冲突以 Git 历史回滚。

9. 自动化工具指引

以下工具位于 scripts/，均以 python scripts/<tool>.py [参数] 运行（仅 bootstrap 用 pwsh）：

场景 工具
Inbox 超龄草稿扫描 vault-inbox-triage
Inbox 智能流转晋级 vault-inbox-consolidate
frontmatter 与链接验证 vault-quality-check [--strict]
重复/高相似笔记检测 vault-dedup
概念 wikilink 自动补全 vault-auto-linker --dry-run
项目主动知识发现 vault-proactive-scan
知识图谱与孤岛分析 vault-graph-analyzer
生成 Canvas 关系图谱 vault-knowledge-graph
精准检索规范与踩坑 search-vault "<query>"
全 Agent 检索 MCP 服务 vault_search_mcp
新项目脚手架初始化 bootstrap
一键综合健康巡检 vault-healthcheck
智能体记忆蒸馏压缩 vault-memory-compactor [--json]