跳到主要内容

配置

.lean-spec/config.json 的完整参考。

配置文件​

LeanSpec 配置存储在项目根目录的 .lean-spec/config.json 中。

默认配置​

{
  "template": "spec-template.md",
  "templates": {
    "default": "spec-template.md"
  },
  "specsDir": "specs",
  "structure": {
    "pattern": "flat",
    "prefix": "",
    "dateFormat": "YYYYMMDD",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "features": {
    "aiAgents": true,
    "examples": true
  }
}

配置选项​

template​

用于新规范的主模板文件。

类型： string
默认： "spec-template.md"

.lean-spec/templates/ 目录中模板文件的路径。

{
  "template": "my-custom-template.md"
}

templates​

不同规范类型的命名模板映射。

类型： object
默认： { "default": "spec-template.md" }

允许您定义多个模板，用户可以在 lean-spec create 或 lean-spec init 期间选择。

{
  "templates": {
    "default": "spec-template.md",
    "minimal": "minimal-template.md",
    "feature": "feature-template.md",
    "bug": "bug-template.md"
  }
}

specsDir​

存储活动规范的目录。

类型： string
默认： "specs"

{
  "specsDir": "specifications"
}

autoCheck​

启用/禁用自动序列冲突检查。

类型： boolean
默认： true

启用后，LeanSpec 在规范创建期间自动检查序列号冲突，如果存在重复则发出警告。

{
  "autoCheck": false
}

structure​

规范文件夹结构和命名的配置。

类型： object

structure.pattern​

文件夹结构模式。

类型： string
值： "flat" | "custom" | 旧模式字符串
默认： "flat"

  • "flat"：规范以扁平结构组织（例如，specs/001-name/）
  • "custom"：使用 groupExtractor 字段的自定义分组
{
  "structure": {
    "pattern": "flat"
  }
}

structure.prefix​

扁平模式中规范文件夹的前缀。

类型： string（可选）
默认： ""（空，使用全局序列号）

常见值：

  • "" - 全局编号（例如，001-name/、002-name/）
  • "{YYYYMMDD}-" - 日期前缀（例如，20251107-001-name/）
  • "spec-" - 自定义前缀（例如，spec-001-name/）
{
  "structure": {
    "pattern": "flat",
    "prefix": "{YYYYMMDD}-"
  }
}

structure.dateFormat​

基于日期的模式的日期格式。

类型： string
默认： "YYYYMMDD"

支持的格式："YYYYMMDD"、"YYYY-MM-DD"、"YYYY-MM"、"YYYY/MM"、"YYYY"、"MM"

{
  "structure": {
    "dateFormat": "YYYY-MM-DD"
  }
}

structure.sequenceDigits​

序列号的位数。

类型： number
默认： 3

  • 3 → 001、002、003
  • 4 → 0001、0002、0003
{
  "structure": {
    "sequenceDigits": 4
  }
}

structure.defaultFile​

每个规范文件夹中的默认文件名。

类型： string
默认： "README.md"

{
  "structure": {
    "defaultFile": "spec.md"
  }
}

structure.groupExtractor​

自定义分组模式的字段提取器。

类型： string（可选）
示例： "{YYYYMMDD}" 或 "milestone-{milestone}"

当 pattern 为 "custom" 时使用，按前置元数据字段动态分组规范。

{
  "structure": {
    "pattern": "custom",
    "groupExtractor": "milestone-{milestone}"
  }
}

structure.groupFallback​

当 groupExtractor 字段缺失时的回退文件夹。

类型： string（可选）

仅用于非日期提取器。当前置元数据字段缺失时，规范被放置在此回退文件夹中。

{
  "structure": {
    "pattern": "custom",
    "groupExtractor": "milestone-{milestone}",
    "groupFallback": "unassigned"
  }
}

features​

可选功能的功能标志。

类型： object

{
  "features": {
    "aiAgents": true,
    "examples": true,
    "collaboration": false,
    "compliance": false,
    "approvals": false,
    "apiDocs": false
  }
}

features.aiAgents​

启用 AI 代理集成（创建 AGENTS.md 文件）。

类型： boolean
默认： true

features.examples​

在模板中启用示例内容。

类型： boolean
默认： true

features.collaboration​

启用协作功能（负责人、审查者字段）。

类型： boolean
默认： false

features.compliance​

启用合规跟踪字段。

类型： boolean
默认： false

features.approvals​

启用审批工作流字段。

类型： boolean
默认： false

features.apiDocs​

在模板中启用 API 文档部分。

类型： boolean
默认： false

frontmatter​

规范前置元数据字段验证的配置。

类型： object（可选）

frontmatter.required​

每个规范中必须存在的字段。

类型： string[]（可选）
默认： ["status", "created"]

{
  "frontmatter": {
    "required": ["status", "created", "priority"]
  }
}

frontmatter.optional​

可能存在但不是必需的字段。

类型： string[]（可选）
默认： ["tags", "priority"]

{
  "frontmatter": {
    "optional": ["tags", "priority", "assignee"]
  }
}

frontmatter.custom​

带类型定义的自定义字段。

类型： object（可选）
默认： {}

支持的类型： "string"、"number"、"boolean"、"array"

{
  "frontmatter": {
    "custom": {
      "epic": "string",
      "sprint": "number",
      "needs_review": "boolean",
      "teams": "array"
    }
  }
}

variables​

模板替换的自定义变量。

类型： object（可选）
默认： {}

变量可以在模板中使用 \{variable_name\} 语法使用。

{
  "variables": {
    "team": "平台工程",
    "company": "Acme Corp",
    "default_reviewer": "alice"
  }
}

完整示例​

{
  "template": "enterprise-template.md",
  "templates": {
    "default": "spec-template.md",
    "minimal": "minimal-template.md",
    "feature": "feature-template.md"
  },
  "specsDir": "docs/specs",
  "autoCheck": true,
  "structure": {
    "pattern": "flat",
    "prefix": "{YYYYMMDD}-",
    "dateFormat": "YYYYMMDD",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "features": {
    "aiAgents": true,
    "examples": true,
    "collaboration": true
  },
  "frontmatter": {
    "required": ["status", "created", "assignee"],
    "optional": ["tags", "priority", "reviewer"],
    "custom": {
      "epic": "string",
      "issue": "string",
      "sprint": "number",
      "estimate": "string",
      "needs_security_review": "boolean",
      "teams": "array"
    }
  },
  "variables": {
    "company": "Acme Corp",
    "team": "平台工程",
    "default_reviewer": "alice",
    "docs_url": "https://docs.acme.com",
    "compliance_email": "compliance@acme.com"
  }
}

验证​

LeanSpec 在加载时验证配置：

  • 必需的结构字段必须有效
  • 自定义字段类型必须有效（string、number、boolean、array）
  • 模板文件必须存在于 .lean-spec/templates/ 中
  • 如果缺少规范目录，则创建

无效的配置将显示带有详细信息的错误。

迁移​

更新配置时：

  1. 编辑 .lean-spec/config.json
  2. 新规范将使用新配置
  3. 现有规范不会自动更新
  4. 如需要手动更新现有规范

下一步：查看 CLI 参考或探索前置元数据字段。