claude-project-manifest

用途

claude-project-manifest 用于为 Claude 项目创建结构化、带注释的文档清单，跟踪项目中的文件、对话线程及其相互关系。适用于以下场景：记录项目内容与结构、创建带注释的文件清单、追踪跨会话的对话历史、构建可导航的知识地图、帮助新协作者了解既有项目。

核心概念

清单结构

清单包含四个主要部分：

Metadata（元数据）：项目级信息，如 ID、版本、状态
Files（文件）：带注释和来源信息的文件清单
Threads（对话线程）：对话摘要与成果记录
Relations（关系）：实体之间的依赖与连接

ID 系统

各实体的 ID 格式如下：

项目：PROJ-{YEAR}-{SEQ}，例如 PROJ-2024-001
文件：FILE-{SEQ}，例如 FILE-042
对话线程：THR-{SEQ}，例如 THR-017
关系：REL-{SEQ}，例如 REL-123

主要能力

最小清单示例

manifest:
  id: "PROJ-2024-001"
  version: "1.0.0"
  created: "2024-01-15T10:30:00Z"

  project:
    name: "My Project"
    description: "Brief description of the project"
    status: active

files:
  - id: "FILE-001"
    path: "src/main.py"
    title: "Main Entry Point"
    summary: "Application entry and initialization"

完整文件条目

files:
  - id: "FILE-001"
    path: "src/main.py"
    type: source  # source | config | doc | asset | generated
    thread_id: "THR-001"
    title: "Main Entry Point"
    summary: "One-line description of purpose"
    notes: |
      Extended annotation explaining:
      - Design decisions made
      - Why this approach was chosen
      - Key implementation details
      - Known limitations or TODOs
    tags: [core, initialization]
    depends_on: ["FILE-002", "FILE-003"]
    created: "2024-01-15T10:30:00Z"
    modified: "2024-01-16T14:20:00Z"

对话线程条目

threads:
  - id: "THR-001"
    started: "2024-01-15T10:30:00Z"
    ended: "2024-01-15T12:45:00Z"
    title: "Initial Project Setup"
    summary: "Created core infrastructure and configuration"
    accomplishments:
      - "Created directory structure"
      - "Implemented Config class with validation"
      - "Added logging infrastructure"
    files_created: ["FILE-001", "FILE-002"]
    files_modified: []
    decisions:
      - "Chose YAML over JSON for config readability"
      - "Used dataclasses instead of Pydantic for simplicity"
    tags: [setup, infrastructure]

关系定义

relations:
  - id: "REL-001"
    type: depends_on
    source: "FILE-001"
    target: "FILE-002"
    annotation: "Main imports and uses Config class"

  - id: "REL-002"
    type: implements
    source: "FILE-003"
    target: "FILE-004"
    annotation: "Repository implements StorageInterface"

关系类型包括：

depends_on：源依赖目标才能运行
extends：源建立在目标之上
implements：源实现目标中定义的接口
references：源引用目标但无硬依赖
supersedes：源替换目标（用于版本管理）

注释编写建议

文件注释应回答：What（这个文件做什么）、Why（为什么选择这个方案）、How（关键实现细节）、Context（创建背景）。示例：

notes: |
  Implements rate limiting using token bucket algorithm.
  Chose token bucket over sliding window for better burst handling.
  Created during THR-003 when API overload issues emerged.
  TODO: Add Redis backend for distributed rate limiting.

对话线程注释应记录：Goal（目标）、Outcome（实际成果）、Decisions（关键决策及理由）、Artifacts（创建或修改的文件）。

使用方式

新项目启动

创建清单文件（manifest.yaml）
添加项目元数据
将初始状态设为 active

开发过程中

对话发生时记录新的对话线程
创建文件时添加带注释的文件条目
依赖关系形成时记录关系
更新对话线程成果

项目交接

查看所有对话线程摘要
确认文件注释为最新
验证所有关系已记录
如需可导出为 Markdown 报告

输出格式

YAML（主要）：适合编辑和版本控制，参见 assets/templates/manifest.yaml
JSON（机器可读）：用于程序化访问，参见 assets/templates/manifest.json
Markdown 报告：供人类阅读的文档导出，参见 assets/templates/manifest-report.md

参考资源

references/manifest-schema.md — 完整模式规范
references/annotation-guidelines.md — 编写有效注释的指南
references/id-systems.md — ID 生成策略
references/workflow-integration.md — 集成模式

技能介绍

用途

核心概念

主要能力

使用方式

参考资源

相关技能