# Dev Skeleton

面向 LLM 辅助开发的 source-first 项目骨架：用短 skill prompts 和模板记录项目目的、非目标、事实来源、稳定约束和 review 偏好，而不是维护一套会过期的实现知识库。

## Metadata

- HTML: https://glenzli.com/projects/dev-skeleton/
- Markdown: https://glenzli.com/projects/dev-skeleton.md
- Collection: Projects
- Language: zh-CN
- Published: 2026-07-02
- Status: active
- Tags: skill, source-first, prompt, review, llm

## Content

Dev Skeleton（仓库名 `dev-skeleton`）是一组面向 LLM 辅助开发的 source-first skill prompts 和可复制模板。它的目标不是把项目压缩成一份实现知识库，而是在模型阅读源码前给出必要方向：项目目的、非目标、事实来源、稳定约束、入口提示和 review 偏好。

它不绑定特定 agent runtime，也不提供 CLI、代码索引、KB 构建器或项目管理流程。真正的事实仍然来自代码、配置、测试、release 产物和维护中的文档；skeleton 只负责让模型知道应该先看什么、不能相信什么、哪些边界不能踩。

## 项目入口

  ![dev-skeleton 将杂乱项目上下文压缩为 source-first 骨架](/images/projects/dev-skeleton-banner.webp)

## 为什么不是知识库

    **Source 是权威**
    代码、配置、测试、release 产物和维护文档才是事实来源；skeleton 不能替代当前源码。

    **Skeleton 只做定向**
    记录目的、非目标、稳定约束、事实来源、domain assumptions、entry hints 和 review priorities。

    **拒绝实现镜像**
    不总结模块、类、函数、调用图、API 或当前行为；这些信息应该让模型按任务阅读源码。

    **少更新，更新准**
    只有长期意图、约束、事实来源或 review 偏好变化时才更新；日常实现改动不应该触发 skeleton 维护。

它解决的是一个很实际的问题：很多“项目上下文”最后会变成过期摘要。摘要越详细，越容易和源码竞争权威。Dev Skeleton 反过来约束自己，只保留稳定方向，把实现判断交还给源码。

## 四个 Skills

      **skeleton-init**
      在目标仓库里创建初始 `DEV_SKELETON.md`、`REVIEW_SKELETON.md` 和 `AGENTS.md`。

```markdown
Create three short orientation files, not a knowledge base.

Read authoritative files:
- README
- manifests and config
- release notes
- tests and schemas
- obvious entrypoints

Capture only durable orientation:
- purpose and non-goals
- truth sources
- constraints
- entry hints
- review priorities
```

初始化阶段最容易写成“项目百科”。这个 skill 的作用是把上下文压回骨架：能从源码读到的行为，不写进 skeleton。

      **skeleton-refresh**
      只在稳定方向变化时刷新骨架，跳过普通重构、helper 改名和测试 churn。

```markdown
Refresh for:
- project purpose or non-goals
- runtime, platform, or release boundaries
- source-of-truth files
- stable domain assumptions
- review priorities or red lines

Skip routine implementation movement.
```

这个 skill 明确反对“每次实现变化都更新文档”。如果变化只影响当前实现，就应该让模型下一次直接读源码。

      **skeleton-audit**
      审查 skeleton 是否开始变成过度详细、陈旧或和源码争权威的 KB。

```markdown
Check:
- Does DEV_SKELETON state purpose, non-goals, truth sources, constraints, and refresh triggers?
- Does REVIEW_SKELETON state review priorities and red lines?
- Does any file summarize modules, classes, functions, or behavior that should be read from source?
- Does any file imply skeleton content is authoritative?
```

输出应以 findings 开头，逐条说明要删除、缩短还是改写。它是维护 skeleton 纪律的刹车。

      **review-skeleton**
      用项目 review 偏好约束审查，但事实判断仍回到 diff、源码、配置、测试和 release 产物。

```markdown
Use skeletons to bias review, not to prove facts.

Read:
- REVIEW_SKELETON.md
- DEV_SKELETON.md when project purpose matters
- actual diff, source, config, tests, and release artifacts

Lead with findings ordered by severity.
```

它适合代码审查、设计审查和变更评估。若 skeleton 和源码冲突，源码用于事实判断，skeleton drift 作为问题报告。

## 文件关系

| 文件或目录 | 作用 |
| --- | --- |
| `skills/skeleton-init/SKILL.md` | 创建三份 source-first skeleton 文件。 |
| `skills/skeleton-refresh/SKILL.md` | 在长期方向变化后刷新 skeleton。 |
| `skills/skeleton-audit/SKILL.md` | 检查过度细节、陈旧声明和 source-first 违规。 |
| `skills/review-skeleton/SKILL.md` | 基于项目 review 偏好做 source-first review。 |
| `templates/DEV_SKELETON.md` | 目标仓库的项目方向骨架模板。 |
| `templates/REVIEW_SKELETON.md` | 目标仓库的 review 偏好模板。 |
| `templates/AGENTS.md` | 目标仓库的 agent 入口模板。 |

## 使用边界

Dev Skeleton 适合那些已经开始用 AI agent 参与开发、但又不想维护一套“项目百科”的仓库。它提供的是短而稳定的 orientation，不是 onboarding 文档、测试手册、release 流程、源码索引或多 agent 调度系统。

当 skeleton 开始解释“当前代码如何工作”时，就应该删掉这部分细节，把模型重新引回源码。