Skip to content

verycafe/project-doc-modes

BranchesTags

Repository files navigation

project-doc-modes

project-doc-modes 是一个 Markdown-first 文档治理 Skill 套件，用来给目标项目建立可持续的文档结构、Reverse Sync、Hook 自动同步和 SDD-RIPER 工作流。

project-doc-modes 当前能力地图

安装

让 AI 助手执行：

Fetch and follow instructions from https://raw.githubusercontent.com/verycafe/project-doc-modes/main/install.md

安装结果是 6 个 Skill 包：

pdm/
pdm-sdd/
pdm-sync/
pdm-verify/
pdm-hook-install/
pdm-hook-uninstall/

默认安装位置：

Codex:       ${CODEX_HOME:-$HOME/.codex}/skills
Claude Code: ${CLAUDE_HOME:-$HOME/.claude}/skills

不要把整个 Git 仓库 clone 成 Skill 目录。仓库里的 README.md、install.md、hooks.md、assets/ 和 scripts/ 是源码与安装辅助文件；最终 Skill 目录只应该包含上面的 6 个 Skill 包。

Claude Code 通过 Skill 包自身暴露 /pdm-*，默认不生成同名 commands/*.md 包装文件；刷新安装会清理旧版 PDM command wrappers，避免 slash suggestions 重复。

六个 Skill

Skill 包 Slash 入口 用途
pdm/ /pdm 初始化、迁移或整理目标项目的文档治理结构。
pdm-sdd/ /pdm-sdd 启用 SDD-RIPER / 规格驱动治理，让 AI 编码前先看 SPEC，编码后同步文档。
pdm-sync/ /pdm-sync 根据最近会话、Hook payload、变更和验证结果做增量 Reverse Sync。
pdm-verify/ /pdm-verify 只读检查文档结构、入口索引、Claude bridge、local-only 策略和路径泄漏。
pdm-hook-install/ /pdm-hook-install 为当前工具、当前项目安装或刷新受管 Stop hook。
pdm-hook-uninstall/ /pdm-hook-uninstall 移除当前工具、当前项目的受管 Stop hook，保留无关 Hook。

简单选择：

只想让仓库文档结构清楚：
/pdm

希望 AI 写代码前先看 SPEC、先有计划、实现后同步文档：
/pdm-sdd

希望每轮会话结束后自动整理文档：
/pdm-hook-install

运行语义

/pdm 会先检查仓库、已有文档、代码目录、配置文件和 git status。如果已有活跃文档，会先复制到 docs/archive/，再迁移为当前结构。它默认只整理文档，不修改代码、依赖、API、测试或运行时行为。

/pdm-sdd 会在文档治理上叠加规格驱动流程：建立或整理 PRD -> PHASE -> SPEC 链路，并维护 CodeMap、Context Bundle、PLAN、REVIEW、IMPLEMENTATION_RECORD 等 SDD-RIPER 所需记录。

/pdm-sync 是 Hook 安全的增量同步模式。它不重新询问模式、不重建文档树、不做全量归档，只把本轮会话和实现事实同步到状态、索引、实现记录、评审、决策或 Release 记录。

/pdm-verify 默认只读：检查根目录 Markdown、docs/ 结构、PRD -> PHASE -> SPEC 层级、入口索引、Claude bridge、local-only 策略和本机路径泄漏。

Hook 自动同步

目标项目完成 /pdm 初始化后，执行：

/pdm-hook-install

默认行为：

  • tool=current
  • scope=project
  • action=bind
  • 只更新名为 pdm sync + verify 的受管 Stop hook
  • 不初始化文档、不迁移文档、不修改代码

Hook 生效前提：

  1. 目标项目已经有活跃文档结构。
  2. 当前工具的 Hook 配置已启用或信任。Codex 如提示审查，使用 /hooks 信任当前项目的 Stop hook；Claude Code 可用 /hooks 查看来源和命令。

默认写入位置：

Codex:
.codex/hooks.json
.codex/hooks/project_doc_modes_stop.py

Claude Code:
.claude/settings.local.json
.claude/hooks/project_doc_modes_stop.py

Codex 和 Claude Code 的 Hook 配置彼此独立。在软件 B 中执行 /pdm-hook-install 不会重新安装、覆盖或删除软件 A 的 Hook。若同一项目要让多个工具都自动同步，需要分别在每个工具中绑定一次，或显式传入 tool=codex / tool=claude-code。

全局绑定和全局卸载必须显式写参数：

/pdm-hook-install scope=global
/pdm-hook-uninstall scope=global

卸载当前项目当前工具的受管 Hook：

/pdm-hook-uninstall

目标项目结构

迭代模式的典型结构：

.
├── AGENTS.md
├── CLAUDE.md          # optional, only when Claude Code support is enabled
├── README.md
└── docs/
    ├── README.md
    ├── archive/
    ├── governance/
    │   ├── STATUS.md
    │   ├── WORKFLOW.md
    │   ├── RELEASES.md
    │   ├── context/
    │   │   ├── CODEMAP.md
    │   │   ├── CONTEXT_BUNDLE.md
    │   │   └── GLOSSARY.md
    │   ├── research/
    │   │   ├── README.md              # 索引表
    │   │   └── YYYYMMDD-HHMMSS-topic-slug.md
    │   └── experience/
    │       ├── README.md              # 索引表
    │       └── YYYYMMDD-HHMMSS-topic-slug.md
    └── product/
        ├── CURRENT.md
        └── v0.1/
            ├── README.md
            ├── requirements/
            ├── phases/
            │   └── PHASE-*/
            │       ├── PLAN.md
            │       ├── REVIEW.md
            │       ├── IMPLEMENTATION_RECORD.md
            │       └── specs/
            └── decisions/

AGENTS.md 是唯一 canonical 规则源。CLAUDE.md 只在需要 Claude Code 时作为 bridge 存在，负责导入或指向 AGENTS.md，不能复制或分叉治理规则。

docs/governance/context/GLOSSARY.md 放项目词汇表。docs/governance/research/README.md 和 docs/governance/experience/README.md 只做索引表；具体调研和经验按任务创建独立 Markdown 文件，放在对应文件夹里：

docs/governance/research/YYYYMMDD-HHMMSS-topic-slug.md
docs/governance/experience/YYYYMMDD-HHMMSS-topic-slug.md

YYYYMMDD-HHMMSS 是该文档创建时的时间，精确到秒，后续编辑不改文件名。新增、重命名或废弃条目时同步更新对应 README 索引表。经验或调研一旦变成需求、约束或验收标准，应 Reverse Sync 到 PRD、PHASE、SPEC 或决策记录。

协作模式会使用 docs/collaboration/ 管理角色、边界、状态和交接文档；SDD-RIPER 可以叠加在任一模式上。

源码结构

本仓库公开运行时入口：

pdm/
pdm-sdd/
pdm-sync/
pdm-verify/
pdm-hook-install/
pdm-hook-uninstall/
scripts/install_runtime.py
scripts/bind_codex_project_hook.py
scripts/bind_claude_code_hook.py
scripts/hook_core/
scripts/verify_repo_integrity.py
install.md
hooks.md
README.md
assets/

Hook 架构采用一个公共入口、一层薄共享核心、每个宿主工具一个 adapter/binder。共享核心只放 active docs guard、受管绑定识别和 JSON/路径 helper；各工具 binder 负责自己的配置文件、Hook schema、事件、payload 和信任/审查模型。

验证

维护本仓库时常用检查：

python3 scripts/install_runtime.py --self-test
python3 scripts/bind_codex_project_hook.py --self-test
python3 scripts/bind_claude_code_hook.py --self-test
python3 scripts/verify_repo_integrity.py

scripts/verify_repo_integrity.py 会检查 README、install、hooks、runtime references、installer 和 .claude-plugin/plugin.json 的关键契约是否一致。

约束

  • 目标项目生成文档默认不进入 Git，除非用户明确要求。
  • 新生成的 docs/archive/ 快照也默认 local-only。
  • 除 AGENTS.md、README.md 和可选 CLAUDE.md bridge 外，其他生成 Markdown 默认放在 docs/ 下。
  • 不修改用户代码、配置、运行逻辑、API、依赖或测试，除非用户明确要求代码变更。
  • SDD-RIPER 下的可执行 SPEC 应包含 Validation Loop。
  • 生成的目标项目文档不得写入本仓库的安装命令、Skill/Hook 实现细节、SKILL.md 或本机安装路径；目标文档应写项目原生规则。

维护文档

本仓库自身的活跃维护文档入口是 docs/README.md。维护文档默认 local-only，除非明确要求，不随源码一起发布。

About

project-doc-modes 是一个用于搭建、整理和迁移仓库文档结构的 Skill。它会先检查仓库现状，再通过简短问答确认开发模式、当前角色、阶段信息和文档语言，然后把仓库组织成“协作模式”或“迭代模式”。它重点处理治理文档、当前入口、角色边界、交接文档和历史归档，同时默认保留现有代码目录，不随意移动代码。它支持中文和英文输出，适合新仓库初始化、旧文档体系迁移，以及为多人协作建立清晰的文档规则。

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages