spec 1.0 · chuẩn tắc

Frontmatter của bản ghi quyết định Leji

Bản dịch có sự hỗ trợ của AI agent. Nếu có khác biệt, trang tiếng Anh là bản có hiệu lực. Nếu bạn thấy vấn đề nào trong văn bản, rất mong bạn mở một issue hoặc gửi một pull request.

Kiểm tra phần frontmatter YAML của một bản ghi quyết định. Phần thân markdown mang bối cảnh, quyết định và hệ quả, viết bằng lời.

$id chuẩn: https://leji.org/schemas/v1.0/decision-record.schema.json
Tệp gốc: decision-record.schema.json

Các trường

#idstringbắt buộc

Định danh ổn định cho quyết định này, ví dụ "adopt-leji".

Mẫu ^[a-z0-9]+(-[a-z0-9]+)*$

#titlestringbắt buộc

Tiêu đề ngắn của quyết định.

#status"proposed" · "accepted" · "superseded" · "deprecated" · "rejected"bắt buộc

Trạng thái vòng đời của quyết định.

#datestringbắt buộc

Ngày ISO 8601 quyết định được đưa ra; ngày này bất biến khi đã công bố, và việc đổi trạng thái về sau không làm nó thay đổi.

Mẫu ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

#decidersmảng chuỗi

Những người đã đưa ra quyết định.

#supersedesstring

id của bản ghi mà quyết định này thay thế.

#supersededBystring

id của bản ghi đã thay thế bản ghi này. BẮT BUỘC khi status là "superseded": một bản ghi đã bị thay thế phải trỏ tới bản kế nhiệm, để liên kết thay thế đi được cả hai chiều.

#affectedPathsmảng chuỗi

Các đường dẫn tương đối so với gốc kho mã nguồn mà quyết định này ảnh hưởng tới.

#affectedCategoriesmảng gồm "domain" · "system" · "practice" · "governance" · "decisions"

Các danh mục nội dung mà quyết định này ảnh hưởng tới.

#linksmảng chuỗi

Các tham chiếu đi ra, ví dụ tới các quyết định hoặc issue liên quan; không bắt buộc.

Schema và ví dụ

SchemaVí dụ · 0001-adopt-leji.md

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://leji.org/schemas/v1.0/decision-record.schema.json",
  "title": "Leji decision record frontmatter",
  "description": "Validates the YAML frontmatter of a decision record. The markdown body carries context, decision, and consequences in prose.",
  "type": "object",
  "required": [
    "id",
    "title",
    "status",
    "date"
  ],
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Stable identifier for this decision, e.g. \"adopt-leji\".",
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
    },
    "title": {
      "description": "Short title of the decision.",
      "type": "string",
      "minLength": 1
    },
    "status": {
      "description": "Lifecycle status of the decision.",
      "enum": [
        "proposed",
        "accepted",
        "superseded",
        "deprecated",
        "rejected"
      ]
    },
    "date": {
      "description": "ISO 8601 date the decision was made; it is immutable once published, and a later status change does not move it.",
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
    },
    "deciders": {
      "description": "People who made the decision.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "supersedes": {
      "type": "string",
      "description": "id of the record this decision replaces."
    },
    "supersededBy": {
      "type": "string",
      "description": "id of the record that replaced this one. REQUIRED when status is \"superseded\": a superseded record must point to its successor so the supersession link is navigable in both directions."
    },
    "affectedPaths": {
      "description": "Repository-root-relative paths the decision affects.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
      }
    },
    "affectedCategories": {
      "description": "Content categories the decision affects.",
      "type": "array",
      "items": {
        "enum": [
          "domain",
          "system",
          "practice",
          "governance",
          "decisions"
        ]
      }
    },
    "links": {
      "description": "Optional outbound references, e.g. to related decisions or issues.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "if": {
    "properties": {
      "status": {
        "const": "superseded"
      }
    },
    "required": [
      "status"
    ]
  },
  "then": {
    "required": [
      "supersededBy"
    ]
  }
}

Một bản ghi quyết định hợp lệ. Schema này kiểm tra phần frontmatter YAML; phần thân markdown mang bối cảnh, quyết định và hệ quả.

---
id: adopt-leji
title: Áp dụng lớp ngữ cảnh Leji
status: accepted
date: 2026-06-10
deciders:
  - Jo Lee
affectedCategories:
  - governance
---

# Áp dụng lớp ngữ cảnh Leji

## Context

Kiến thức kỹ thuật nằm trong đầu người, trong các luồng chat, và trong ba tệp cấu hình công cụ ngày càng lệch nhau. Agent sinh ra mã không khớp với các bất biến của chúng tôi, bởi vì các bất biến đó chưa được viết ở bất cứ nơi nào một công cụ có thể đọc.

## Decision

Áp dụng Leji ở mức `indexed`: manifest, boot profile, nội dung domain và system, các bản ghi quyết định, index được sinh ra, changelog cho máy.

## Consequences

Các tệp cấu hình của nhà cung cấp trở thành những dòng chuyển hướng một dòng. Việc sửa ngữ cảnh đi cùng chính những PR làm lộ ra vấn đề. Jo là chủ sở hữu lớp ngữ cảnh.

← Tất cả schema