文档

Coograph 是面向 AI 编程代理的图优先上下文层。开源核心在 代码仓库，MIT 许可。这套文档是简版。仓库的 README 是完整版，以那里为准。

从哪里开始

• 快速开始 — 安装、首次构建、首次查询。
• 代码图 — 图里有什么、怎么构建、怎么查询。
• 工作流 — Plan → Propose → Apply → Review → Archive，以及驱动它的代理。
• OpenSpec — 每次改动所用的四个文件、门禁，以及归档如何反哺 Retro。
• 模型 — 让每个代理跑在不同模型上：需要你主动开启，从不替你默认，而且每次都会告诉你用了哪个。
• Retro — 记录规则被打破的时刻和每次会话的 token 成本，以 OpenSpec 形式提出对指令和 hook 的修改。

两条姿态准则

Coograph 初始化的每个项目都附带两条不可妥协的准则。两条都作为 banner 写在 CLAUDE.md 和 .github/copilot-instructions.md 顶部：

• CODE-GRAPH FIRST — 代码图优先 —— 任何代码库导航都先从图查询开始。grep 只是兜底，只有图确实不在时才用。
• OPENSPEC OR STOP — — 涉及多文件或行为变化的改动，必须先提 OpenSpec 提案、用户批准，才能写代码。

两条准则都被设计成「对话中途不会忘记」。详见 工作流。

仓库结构

.github/code-graph/      — MCP server, parsers, git hooks
.github/agents/          — Planner, Reviewer, Debugger, Verifier, Explore, Retro
.github/skills/          — coograph-propose, coograph-apply, etc.
.github/retro/           — Retro analyzer, rule registry, README
.github/scripts/         — Drift, idempotency and plugin-sync checks
.claude/hooks/           — Lifecycle hooks (block-generated, log-bash, capture-signals, …)
.agents/ .codex/ .opencode/ — Per-tool native config
plugin/                  — Generated Claude Code plugin
.claude-plugin/          — Marketplace manifest
openspec/changes/        — Active proposals
openspec/changes/archive/— Completed proposals
examples/                — A finished initialized project

许可

MIT。开源核心永久免费。Pro 提供定制服务 —— 见 /pro。