Skip to content

Commit 7bab37f

Browse files
committed
feat: strengthen README governance
1 parent 7203579 commit 7bab37f

18 files changed

Lines changed: 488 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,26 @@
1010
DevCodex 通过 `.github/`(Copilot)、`CLAUDE.md + .claude/ + .mcp.json`(Claude Code)以及 `AGENTS.md + .agents/ + .codex/`(Codex)向受支持的 AI 编码客户端注入结构化的开发工作流规范。
1111
在支持 Hooks 的宿主中,它优先用 `hooks/_runtime/lifecycle.cjs` 提供确定性的生命周期护栏;在不支持 Hooks 的宿主中,则回退到 instructions 语义层继续工作。
1212

13+
## 目录导航
14+
15+
- [DevCodex 是什么?](#devcodex-是什么)
16+
- [功能特性](#功能特性)
17+
- [安装](#安装)
18+
- [使用](#使用)
19+
- [正式需求与执行模板边界](#正式需求与执行模板边界)
20+
- [默认执行原则](#默认执行原则)
21+
- [CLI 命令](#cli-命令)
22+
- [`.devcodex` 工作区集中布局(v1.10.0+)](#devcodex-工作区集中布局v1100)
23+
- [本地开发](#本地开发)
24+
- [架构概览](#架构概览)
25+
- [客户端支持矩阵(Client Support Matrix)](#客户端支持矩阵client-support-matrix)
26+
- [IDE 兼容性](#ide-兼容性)
27+
- [文档](#文档)
28+
- [边界声明](#边界声明)
29+
- [Tier 说明](#tier-说明)
30+
- [Agent 入口](#agent-入口)
31+
- [许可证](#许可证)
32+
1333
## 功能特性
1434

1535
- **8 种工作流**: `dev` / `fix` / `audit` / `analyze` / `self-fix` / `resume` / `plan` / `chat`
@@ -22,6 +42,7 @@ DevCodex 通过 `.github/`(Copilot)、`CLAUDE.md + .claude/ + .mcp.json`(C
2242
- **全模式入口检查**: 所有模式在实质任务前显示 PC0~PC7;dev 模式额外执行 PC4 规范雷达与完整合规链
2343
- **项目现实扩展**: 先做语义意图初判,再结合目标项目 Profile、目录与当前任务上下文修正最终路由、产物落点和验证方式
2444
- **支撑型 Skill**: `execution-contract` / `test-router` / `release-verification` / `host-contract-verification` / `source-consumer-sync` 为控制面、多批次、测试路线、宿主契约验证与真相源-消费者同步提供可审计支撑,不新增工作流分支
45+
- **README 专项能力**: `readme-authoring` 负责 README 用户/使用者优先写作,`audit-readme` 负责 README / 用户使用文档专项 review
2546
- **执行闭环复审**: dev/fix 完成前执行 ECR 执行闭环复审,交叉验证 CP 产物、报告、daily memory、SUMMARY、diff/commit、测试/探针与 dirty 边界
2647
- **推荐结论**: analyze/audit/report 多建议或多路径场景必须给出推荐结论与推荐理由;无后续动作时明确写“推荐:无后续动作”
2748
- **确认交互降级**: 用户确认先抽象为 ConfirmationRequest,再按宿主能力选择按钮、权限提示、Hook 阻断或文本确认 fallback,不把按钮 UI 承诺为全宿主能力
@@ -60,7 +81,7 @@ npx @vextjs/devcodex init --codex # 仅 Codex adapter
6081
├── copilot-instructions.md ← 默认 Copilot always-on 总则(新增)
6182
├── instructions/ ← Instructions 约束(12 个,含全部工作流规则)
6283
├── agents/ ← Copilot 自定义 Agent(v1.9.8 起恢复默认分发)
63-
├── skills/ ← Skill 详细检查标准(41 个,按需读取,含 spec-governance 与 5 个支撑型 Skill)
84+
├── skills/ ← Skill 详细检查标准(43 个,按需读取,含 README 专项能力、spec-governance 与 5 个支撑型 Skill)
6485
├── prompts/ ← Prompt 模板(26 个)
6586
├── hooks/ ← 宿主生命周期 Hook 配置与运行时
6687
│ ├── devcodex.lifecycle.json
@@ -246,7 +267,7 @@ devcodex/
246267
├── instructions.md # 单源规范文件;安装时按平台生成 copilot-instructions.md / CLAUDE.md / AGENTS.md
247268
├── agents/ # Agent 源文件;Copilot 端默认分发,Claude Code 端不分发
248269
├── instructions/ # 全局 Instructions(12 个,含工作流规则摘要,自动注入)
249-
├── skills/ # Skill 详细检查标准(41 个,按 01-common §按需读取表 路由读取)
270+
├── skills/ # Skill 详细检查标准(43 个,按 01-common §按需读取表 路由读取)
250271
├── prompts/ # Prompt 模板(26 个)
251272
├── hooks/ # Workspace Hooks 配置与分发到 `.github/hooks/_runtime/` 的运行时
252273
├── codex/ # Codex Hook 配置源,分发到 `.codex/hooks.json`
@@ -261,6 +282,8 @@ devcodex/
261282

262283
控制面与长流程当前有五类支撑型 Skill:`execution-contract` 约束 scope / allowedPaths / requiredArtifacts / consumerScope / validationRoute / deviationLog,`test-router` 统一选择验证路线,`release-verification` 在正式 tag / publish 前执行 R0~R7 发布验证链,`host-contract-verification` 负责 direct replay / fixture replay / bootstrap / workspace guard 证据,`source-consumer-sync` 负责 Concept Sync Map 与当前消费者同步边界。
263284

285+
README / 用户使用文档当前补充两类专项 Skill:`readme-authoring` 负责把 README 默认主视角收口为用户 / 使用者优先,`audit-readme` 负责专项审查用户路径、快速开始、示例真实度、开发信息后置与消费链一致性。
286+
264287
&gt; ℹ️ 维护者状态文件(本仓库开发过程中累积的 violations/pending-fixes 记录)按 active-root 保存,例如 workspace-namespace 下的 `.devcodex/<project>/data/`,**不分发**给用户。
265288

266289
## 客户端支持矩阵(Client Support Matrix)

‎changelogs/unreleased.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,7 @@
1111
- 控制面 / 长流程 / 多批次变更写入本文件时,优先标明 `execution-contract`、`test-router`、`release-verification`、`host-contract-verification`、`source-consumer-sync` 等支撑型能力是否同步更新。
1212
- 宿主输出、Hook 或项目现实扩展相关条目,建议显式写出 `verified-present / verified-missing / unverified`、sticky `activeProject` 与用户可见 `意图扩展摘要` 是否发生变化。
1313
- 执行闭环、确认机制或发布门禁相关条目,建议补充 `Intent Expansion Card`、`ConfirmationRequest`、`ECR` 与验证证据,方便正式发版时直接归档到版本 changelog。
14+
15+
## 2026-05-29
16+
17+
- README 治理增强:新增 `readme-authoring` / `audit-readme`,将 README 默认主视角收口为用户 / 使用者优先,并补 `V38`、`test-readme-governance`、资产口径同步与专项 README review。

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
},
99
"scripts": {
1010
"test": "node scripts/validate-versions.js && node scripts/validate.js",
11-
"test:all": "npm test && node scripts/test-spec-governance.js && node scripts/test-hooks-runtime.js && node scripts/test-instruction-fallback-check.js && node scripts/test-mcp-servers.js && node scripts/test-migrate-layout.js && node scripts/test-cli-behavior.js && node scripts/test-pack-clean.js && npm --prefix website run build && node scripts/check-syntax.js",
11+
"test:all": "npm test && node scripts/test-spec-governance.js && node scripts/test-readme-governance.js && node scripts/test-hooks-runtime.js && node scripts/test-instruction-fallback-check.js && node scripts/test-mcp-servers.js && node scripts/test-migrate-layout.js && node scripts/test-cli-behavior.js && node scripts/test-pack-clean.js && npm --prefix website run build && node scripts/check-syntax.js",
1212
"test:all:with-audit": "npm run test:all && npm run test:audit",
1313
"test:audit": "npm audit --omit=dev && npm --prefix website audit --omit=dev",
1414
"test:cli-behavior": "node scripts/test-cli-behavior.js",
@@ -17,6 +17,7 @@
1717
"test:migrate-layout": "node scripts/test-migrate-layout.js",
1818
"test:version": "node scripts/validate-versions.js",
1919
"test:pack-clean": "node scripts/test-pack-clean.js",
20+
"test:readme-governance": "node scripts/test-readme-governance.js",
2021
"test:spec-governance": "node scripts/test-spec-governance.js",
2122
"validate": "node scripts/validate.js"
2223
},

‎plugin.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,11 @@
160160
"file": "skills/audit-document/SKILL.md",
161161
"tier": "free"
162162
},
163+
{
164+
"id": "audit-readme",
165+
"file": "skills/audit-readme/SKILL.md",
166+
"tier": "free"
167+
},
163168
{
164169
"id": "audit-execution-guide",
165170
"file": "skills/audit-execution-guide/SKILL.md",
@@ -190,6 +195,11 @@
190195
"file": "skills/document-sync/SKILL.md",
191196
"tier": "free"
192197
},
198+
{
199+
"id": "readme-authoring",
200+
"file": "skills/readme-authoring/SKILL.md",
201+
"tier": "free"
202+
},
193203
{
194204
"id": "impact-review",
195205
"file": "skills/impact-review/SKILL.md",

‎prompts/project-readme.prompt.md‎

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
22
agent: agent
3-
description: 项目 README 模板,用于生成适配库/服务/应用/工具项目的通用 README
3+
description: 项目 README 模板,用于生成面向用户/使用者、适配库/服务/应用/工具项目的 README
44
applyTo: README.md
55
---
66
# 项目 README 模板
77

88
> **触发**: `dev-init/SKILL.md` 初始化项目 / `dev-docs/SKILL.md` 更新文档
99
> **要求**: 生成的 Markdown README 必须包含 `## 目录导航`
10+
> **默认主视角**: 用户 / 使用者优先,开发与贡献信息后置
1011
> **先判断项目类型**: `library` / `service` / `application` / `tool`
1112
1213
---
@@ -21,18 +22,25 @@ applyTo: README.md
2122
## 目录导航
2223

2324
- [项目简介](#项目简介)
25+
- [适用对象与使用场景](#适用对象与使用场景)
2426
- [能力概览](#能力概览)
2527
- [快速开始](#快速开始)
26-
- [开发方式](#开发方式)
28+
- [常见用法](#常见用法)
2729
- [配置](#配置)
2830
- [文档与接口](#文档与接口)
29-
- [常见问题](#常见问题)
30-
- [贡献与协作](#贡献与协作)
31+
- [常见问题与排错](#常见问题与排错)
32+
- [开发与贡献](#开发与贡献)
3133
- [许可证](#许可证)
3234

3335
## 项目简介
3436

35-
> 用 2~5 句话说明项目定位、目标用户、运行场景和当前边界。
37+
> 用 2~5 句话说明项目定位、真实使用者、运行场景和当前边界。
38+
39+
## 适用对象与使用场景
40+
41+
- 这份 README 默认先写给谁看(用户 / 使用者 / 协作方)
42+
- 适合什么场景,不适合什么场景
43+
- 如果这是内部项目,也要把“用户 / 使用者”理解为真实文档读者,而不是营销对象
3644

3745
## 能力概览
3846

@@ -72,14 +80,10 @@ npm run dev
7280

7381
> 写清如何启动界面、CLI 或本地工作流。
7482
75-
## 开发方式
83+
## 常见用法
7684

77-
| 项 | 内容 |
78-
|----|------|
79-
| Node / 包管理器 | |
80-
| 启动命令 | |
81-
| 测试命令 | |
82-
| 类型检查 / lint | |
85+
- 用户完成快速开始后,最常见的下一步操作是什么
86+
- 给出 1~3 个最短、最真实的使用示例
8387

8488
## 配置
8589

@@ -94,17 +98,22 @@ npm run dev
9498
- 接口文档:
9599
- 发布 / 变更日志:
96100

97-
## 常见问题
101+
## 常见问题与排错
98102

99103
### Q1.
100104

101105
-
102106

103-
## 贡献与协作
107+
## 开发与贡献
104108

105-
- 代码规范:
106-
- 提交约定:
107-
- 协作说明:
109+
| 项 | 内容 |
110+
|----|------|
111+
| Node / 包管理器 | |
112+
| 启动命令 | |
113+
| 测试命令 | |
114+
| 类型检查 / lint | |
115+
| 代码规范 / 提交约定 | |
116+
| 协作说明 | |
108117

109118
## 许可证
110119

@@ -117,3 +126,4 @@ npm run dev
117126
2. 私有服务项目默认不要写 npm badge、MIT、开源安装指令作为主叙事
118127
3. README 必须有 `## 目录导航`
119128
4. 只保留与当前项目类型相关的示例块,其他类型可删除或标 `N/A`
129+
5. 默认先满足用户 / 使用者的“理解 -> 快速开始 -> 常见用法 -> 配置 -> 排错”路径,再写开发与贡献信息

‎scripts/test-readme-governance.js‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
#!/usr/bin/env node
2+
'use strict'
3+
4+
const fs = require('fs')
5+
const path = require('path')
6+
7+
const ROOT = path.resolve(__dirname, '..')
8+
const failures = []
9+
10+
function read(file) {
11+
return fs.readFileSync(path.join(ROOT, file), 'utf8')
12+
}
13+
14+
function mustInclude(file, needle) {
15+
if (!read(file).includes(needle)) failures.push(`${file} missing "${needle}"`)
16+
}
17+
18+
function mustExist(file) {
19+
if (!fs.existsSync(path.join(ROOT, file))) failures.push(`missing file: ${file}`)
20+
}
21+
22+
function assertOrder(file, headings) {
23+
const text = read(file)
24+
let previous = -1
25+
for (const heading of headings) {
26+
const index = text.indexOf(heading)
27+
if (index === -1) {
28+
failures.push(`${file} missing heading "${heading}"`)
29+
return
30+
}
31+
if (index < previous) {
32+
failures.push(`${file} heading order drift: "${heading}" appears before an earlier user-path section`)
33+
return
34+
}
35+
previous = index
36+
}
37+
}
38+
39+
const plugin = JSON.parse(read('plugin.json'))
40+
for (const [id, file] of [
41+
['readme-authoring', 'skills/readme-authoring/SKILL.md'],
42+
['audit-readme', 'skills/audit-readme/SKILL.md']
43+
]) {
44+
mustExist(file)
45+
if (!plugin.skills.some(skill => skill.id === id && skill.file === file)) {
46+
failures.push(`plugin.json missing ${id} skill entry`)
47+
}
48+
}
49+
50+
for (const [file, needle] of [
51+
['skills/readme-authoring/SKILL.md', 'primaryAudience'],
52+
['skills/readme-authoring/SKILL.md', 'userJourney'],
53+
['skills/readme-authoring/SKILL.md', 'consumerMap'],
54+
['skills/readme-authoring/SKILL.md', '用户 / 使用者'],
55+
['skills/audit-readme/SKILL.md', 'RM-1 用户路径完整性'],
56+
['skills/audit-readme/SKILL.md', 'RM-6 消费链一致性'],
57+
['skills/dev-docs/SKILL.md', 'readme-authoring'],
58+
['skills/dev-docs/SKILL.md', 'audit-readme'],
59+
['skills/dev-init/SKILL.md', 'readme-authoring'],
60+
['skills/document-sync/SKILL.md', 'readme-authoring'],
61+
['skills/document-sync/SKILL.md', 'audit-readme'],
62+
['skills/audit-document/SKILL.md', 'audit-readme'],
63+
['skills/audit-execution-guide/SKILL.md', 'audit-readme'],
64+
['prompts/project-readme.prompt.md', '用户 / 使用者优先'],
65+
['README.md', 'readme-authoring'],
66+
['README.md', 'audit-readme'],
67+
['website/docs/intro/index.md', 'readme-authoring'],
68+
['website/docs/specs/directory-structure.md', 'audit-readme']
69+
]) {
70+
mustInclude(file, needle)
71+
}
72+
73+
assertOrder('prompts/project-readme.prompt.md', [
74+
'## 项目简介',
75+
'## 适用对象与使用场景',
76+
'## 快速开始',
77+
'## 常见用法',
78+
'## 配置',
79+
'## 文档与接口',
80+
'## 常见问题与排错',
81+
'## 开发与贡献'
82+
])
83+
84+
const pkg = JSON.parse(read('package.json'))
85+
if (pkg.scripts['test:readme-governance'] !== 'node scripts/test-readme-governance.js') {
86+
failures.push('package.json missing test:readme-governance script')
87+
}
88+
if (!pkg.scripts['test:all'] || !pkg.scripts['test:all'].includes('node scripts/test-readme-governance.js')) {
89+
failures.push('package.json test:all missing readme governance targeted test')
90+
}
91+
92+
if (failures.length) {
93+
console.error('README governance checks failed:')
94+
for (const failure of failures) console.error(`- ${failure}`)
95+
process.exit(1)
96+
}
97+
98+
console.log('README governance checks passed')

0 commit comments

Comments
 (0)