把一个普通代码仓库，初始化成适合 AI Agent 协作的开发框架：上下文可导航、需求可验证、文档可治理、Skill 可复用。
语言：中文 · English
LinkSpec 是一个开发期 CLI 脚手架。它不是新的运行时框架，也不是一组 prompt 模板，而是把一套 AI 原生研发协作机制 注入到项目里：
- 用结构化文档给 Agent 稳定上下文，降低长对话里的语义漂移。
- 用 Gherkin 验收契约替代散文式 PRD，把"符合预期"变成可执行测试。
- 用机器门禁保证文档与代码同步，避免 Agent 高频改代码后文档快速腐烂。
- 用
.ai/单一事实源治理 skill 和项目 prompt，让 Claude Code、Codex 等工具共享同一套资产。
一句话：LinkSpec 关注的不是"让 AI 多写代码"，而是让 AI 写出来的代码处在可理解、可验证、可维护的工程约束里。
当 AI Agent 成为代码改动的主力后，传统研发流程会暴露几个新问题：
| 问题 | 常见表现 | LinkSpec 的处理方式 |
|---|---|---|
| 上下文漂移 | 长对话越跑越偏，Agent 混淆模块边界、状态机、历史约束 | 用仓库级文档入口和分层 docs 给 Agent 明确查阅路线 |
| 文档腐烂 | 一天几十次代码改动后，接口、Schema、MQ 文档迅速落后 | 用 doc-sync 规则把"改代码必须改文档"变成 pre-commit/CI 门禁 |
| 需求歧义 | PRD 写"正确处理重复上传"，Agent 自行脑补"正确"的含义 | 用 acceptance.feature 写成 Given/When/Then，并转为测试 |
| Skill / Prompt 漂移 | .claude/skills、.agent/skills、CLAUDE.md、AGENTS.md 多副本不同步 |
用 .ai/ 作为唯一物理源，再软链到各工具固定路径 |
| 经验浪费 | 一个模块里反复纠偏出来的经验，下个模块又重新试错 | 用 skill 注册表和校验机制把试错经验资产化 |
这套机制来自真实项目里从"口头沟通"到"重模板文档"再到"契约化开发"的迭代。它的重点不是把流程写得更厚，而是把容易出错的隐式约定变成显式、可检查、可复用的工程资产。
linkspec init 会在项目中建立 4 个支柱和 1 条门禁脊柱。
① Skill 库 + 治理 .ai/skills/ + README 注册表 + check-skills
② 文档分层治理 docs/{api,internals,ops} + doc-sync 规则
③ Spec-as-Test 工作流 .specs/<feature>/brief.md
→ acceptance.feature
→ technical_design.md
→ Code + Tests
④ 多工具 AI 资产装配 .ai/ 唯一源
→ .claude/.agent/CLAUDE.md/AGENTS.md
────────────────────────────────────────────────────────────
门禁脊柱 check-skills · check-docs-sync
· check-docs-facts · check-ai-links
LinkSpec 初始化后的项目会有面向 Agent 的统一入口和分层文档：
docs/api/：HTTP、MQ、Schema、错误码等对外契约。docs/internals/：模块边界、核心流程、状态机、内部约定。docs/ops/：部署、配置、运行维护。
文档按读者和稳定性切分，避免把架构、接入、运维步骤混在一起。Agent 不需要扫描整个代码库来猜项目结构，而是先从入口文档拿到"该读什么、不要读什么、哪些事实是权威"的导航。
更重要的是，LinkSpec 不把"请记得同步文档"留给自觉。doc-sync-rules.yaml 会声明代码路径和文档路径的契约关系，check-docs-sync 在提交前检查：代码改了，关联文档没动，就拦下。
LinkSpec 的 feature 工作流不是传统的"PRD 越写越厚"，而是三段职责分离：
| 产物 | 回答的问题 | 主要读者 |
|---|---|---|
brief.md |
为什么做、做什么、不做什么、涉及哪些模块 | 开发者 + Agent |
acceptance.feature |
什么叫做对了 | 开发者 + Agent + 测试框架 |
technical_design.md |
在哪里做、怎么做、改哪些文件 | Agent + Reviewer |
acceptance.feature 使用 Gherkin 表达验收契约。例如：
Scenario: 重复上传同一文件
Given 已存在 task=T1 hash=abc123 status=PARSED
When alice 再次提交 PDF hash=abc123
Then 接口返回 task_id=T1
And 不创建新任务
And 不发送 MQ 消息这种写法会强迫团队在编码前做出业务决定。它把"用户上传 PDF 后系统应正确处理重复上传"这种自然语言歧义，转换成可审阅、可执行、可回归的断言。
LinkSpec 把 .ai/skills/ 当成团队方法论库，而不是 prompt 垃圾箱。
每个 skill 需要声明：
- 它什么时候应该被使用。
- 它跟踪哪些代码或文档路径。
- 它属于 LinkSpec 套件托管，还是项目自有。
check-skills 会校验注册表、frontmatter、死链和技术栈一致性。这样一个项目里沉淀出来的"某类任务怎么做"，可以在后续类似任务里稳定复用，而不是每次重新靠对话纠偏。
不同 AI 工具有不同的固定加载路径：
- Claude Code 读取
.claude/skills/、CLAUDE.md - Codex / AGENTS 生态读取
.agent/skills/、AGENTS.md - 其他工具可能还有自己的目录约定
LinkSpec 不复制多份内容，而是把真实文件收敛到 .ai/：
.ai/skills ← .claude/skills, .agent/skills
.ai/prompts/project.md ← CLAUDE.md, AGENTS.md
这解决的是结构问题，而不是靠"改 A 记得改 B"的流程补丁。check-ai-links 会检查软链是否被误删、误替换成实目录。
需要 Python 3.9+。如果使用 npm 入口，还需要 Node.js 16+。
A. npm 安装
npm install -g linkspec
linkspec --help
# 免安装试用
npx linkspec --helplinkspec 的 npm 包是一个 Node 启动器：首次运行时会在 ~/.linkspec/venv 建立隔离 Python 环境，然后转发到 Python CLI。
B. Python 原生安装
pipx install git+https://github.com/ql-link/LinkSpec
# 或免安装
uvx --from git+https://github.com/ql-link/LinkSpec linkspec --helplinkspec init my-app # 初始化一套 AI 协作开发框架
cd my-app
linkspec status # 查看装配状态
linkspec check # 手动运行门禁
linkspec add skill <name> # 添加套件 skill 或项目自有 skill
linkspec upgrade # 更新通用引擎，不覆盖项目内容初始化后，项目会得到类似结构：
your-project/
├── .ai/
│ ├── skills/ # Skill 库 + 注册表
│ └── prompts/project.md # 项目级 Agent 入口提示
├── .claude/skills -> .ai/skills
├── .agent/skills -> .ai/skills
├── CLAUDE.md -> .ai/prompts/project.md
├── AGENTS.md -> .ai/prompts/project.md
├── docs/
│ ├── api/ # 对外契约
│ ├── internals/ # 内部实现与边界
│ └── ops/ # 部署与运行
├── .specs/ # feature 临时产物
├── scripts/
│ ├── quality/ # 文档、skill、软链门禁
│ ├── setup/ # AI 资产软链装配
│ └── acceptance/ # spec 阶段守卫
├── constitution.yaml # 项目宪法：路径、技术栈、契约、启用项
└── .pre-commit-config.yaml # 门禁入口
原始需求
↓
brief.md
- 需求摘要
- 业务流程
- 核心模块与实现思路
- 风险与不确定性
- 待确认问题
↓
acceptance.feature
- Gherkin 验收契约
- 可接入 pytest-bdd 等测试框架
↓
technical_design.md
- 改动文件树
- 方法级实现方案
- 数据、API、MQ、异常、测试设计
↓
Code + Tests
↓
linkspec check / pre-commit / CI
这个流程的目标是让 Agent 在动手前已经拿到三类约束：
- 业务约束：brief 说明为什么做、边界在哪里。
- 验收约束：feature 文件说明什么叫做对。
- 实现约束：technical design 说明在哪里改、怎么集成。
| 命令 | 作用 |
|---|---|
linkspec init <proj> |
交互式填写项目宪法，渲染模板，铺设脚本，建立软链，安装门禁 |
linkspec status |
查看 skill 数量、门禁状态、软链状态、constitution 完整性 |
linkspec check |
手动运行质量门禁，可按维度单独执行 |
linkspec add skill <name> |
从套件库安装 skill，或创建项目自有 skill |
linkspec upgrade |
更新 LinkSpec 通用引擎，不覆盖项目的 constitution、docs、skills |
LinkSpec 能注入任意项目，靠的是把两类东西分开：
| 类型 | 内容 | 升级策略 |
|---|---|---|
| 引擎 | 校验脚本、装配脚本、阶段守卫、模板渲染逻辑 | linkspec upgrade 可以更新 |
| 配置 | 源码路径、技术栈、跨服务契约、doc-sync 规则、启用的 skill | 项目拥有，LinkSpec 不覆盖 |
项目专有事实集中在 constitution.yaml。例如源码路径、测试命令、MQ topic 命名空间、哪些代码变化必须同步哪些文档，都应该在这里声明。
这使得 LinkSpec 既能提供统一的工程机制，又不把某个项目的业务假设硬编码进套件。
LinkSpec 更适合这些场景：
- 团队大量使用 Claude Code、Codex、Cursor 等 AI 编程工具。
- 没有专职产品经理，开发者需要兼任需求澄清和验收定义。
- 项目存在跨模块、跨语言、跨服务契约，例如 API、MQ、数据库 Schema。
- 文档已经开始失去可信度，或者每次靠 reviewer 人肉提醒同步文档。
- 团队想把反复纠偏出来的开发经验沉淀成可复用 skill。
它不适合这些场景：
- 只想要一个轻量 prompt 模板集合。
- 不愿意把验收、文档、门禁纳入开发流程。
- 项目没有多人或多 Agent 并发协作问题。
- kit-docs/design.md：设计蓝图与命令规划
- kit-docs/architecture.md：4 支柱 + 门禁脊柱
- kit-docs/skill-tiering.md：skill 可移植性定级
- kit-docs/contributing.md：贡献套件 skill 与引擎的方式
MIT