尧图网站建设 
Maka 架构文档写作方法论用 article-template 写出一篇既易读又精确的双语架构文章【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文围绕 skills/maka-architecture-docs/assets/article-template.md 展开系统讲解 MakaApache Maka, Incubating沉淀下来的架构文档写作模板与配套方法论从 Frontmatter 元数据、十一节叙事骨架到文章契约、四层解释、生命周期状态分离、双语语义对等与质量门禁。读完本文你可以直接使用这套模板为 Maka Runtime 的任何组件或机制写出像技术博客一样易读、又保持架构记录级精确的双语架构文章并知道如何用仓库中的源码、测试、ADR 作为证据锚点。为什么需要一套架构文档模板Agent 运行时Runtime的架构文档面临一对天然矛盾可进入性新工程师能快速读懂与精确性实现细节、状态机、失败路径不能含糊。Maka 团队在长期维护运行时文档后发现常见文档存在几类结构性问题从服务清单或组件清单开篇读者记住了名词却不知道系统解决什么问题把 Planned计划中行为当作 Current已实现行为书写误导后续维护者只讲 happy path回避超时、中断、取消、部分成功等真实失败路径中英文版本逐句直译语义漂移后中文版和英文版承诺了不同的结论。article-template.md正是为此设计的一个写作起点脚手架starting scaffold而不是强制性的目录清单。它的定位在 skills/maka-architecture-docs/SKILL.md 中有明确说明Useassets/article-template.mdas a starting scaffold only when it fits the chosen subject; remove irrelevant sections rather than filling them mechanically.即模板服务于主题而非主题服务于模板不相关的章节应删除而不是机械填满。模板全景元数据与章节骨架模板由两部分组成YAML Frontmatter元数据和 Markdown 章节骨架。以下是模板的实际结构摘自 article-template.md。Frontmatter 元数据字段字段取值示例含义doc_idarchitecture.subject文档稳定 ID用于双语对照与跨文档引用titleReader-oriented title面向读者的标题而非组件名languagezh-CN/en本文语言source_languagezh-CN/en源语言用于翻译周期管理counterpart./counterpart-filename.md对应语言版本的相对路径implementation_statuscurrent/planned/exploratory/deprecated/historical所述行为在系统中的实现状态document_statusdraft/stable/deprecated/historical文档自身的成熟度状态translation_statussynced/needs-update/source-only双语同步状态last_verifiedYYYY-MM-DD最后核验日期ownersmaka-backend文档责任人这套元数据在仓库的docs/architecture目录中已被实际采用。例如 docs/architecture/runtime-resume-architecture.md 的 Frontmatter 写着doc_id: architecture.runtime-resume、implementation_status: phase_0_2_and_phase_3a_authority_current、translation_status: synced、last_verified: 2026-09-02、owners: [maka-backend]其双语对照版本 docs/architecture/runtime-resume-architecture.zh-CN.md 也遵循相同约定。十一节章节骨架模板建议的章节顺序与每个章节的写作提示如下# Reader-oriented title面向读者的标题。开头摘要blockquoteIn one paragraph: what question this article answers, the conclusion, and why it matters.——用一段话回答这篇文章回答什么问题、结论是什么、为什么重要。Why this matters描述工程问题或读者问题明确范围与相关排除项scope and relevant exclusions。Mental model给出最简单且正确的直觉在依赖任何术语前先定义它。A concrete scenario引入一个贯穿全文的代表性示例。How it works解释机制、时序、数据与组件职责只添加能回答具体问题的图。State and invariants描述生命周期、持久/易失状态、合法转换、所有权、排序与必须保持为真的条件。Boundaries明确该机制拥有什么、委托什么、明确不保证什么。Failure and recovery覆盖超时、中断、取消、重试、部分成功、恢复与不可恢复失败。Decisions and trade-offs解释所选设计、可信替代方案、收益、代价与重新评估条件。Code and operational map指向稳定模块、类型、接口、schema、测试、日志、trace 与 metrics匹配承诺的阅读深度。Known limitations and future direction将 Current、Planned、Exploratory 的主张显式分开。Further reading链接相关的架构文档、ADR、API 规范与代码自有引用。模板末尾有一句重要注释Remove any section that does not help answer this articles core question.——这是整个模板的运作原则结构围绕核心问题裁剪。写作契约动笔前先定六件事skills/maka-architecture-docs/references/writing-standard.md 要求动笔前先确立文章契约article contractCore question本文必须回答的唯一问题Audience新人、活跃开发者、技术负责人、外部集成方或有意组合Reading depth导向orientation、工作理解working understanding或实现/调试深度implementation/debugging depthScope覆盖什么、明确不覆盖什么Evidence basis代码、测试、schema、运行时观测、已接受的决策或提案Lifecycle statusCurrent / Planned / Exploratory / Deprecated / Historical。一篇文档可以通过渐进披露progressive disclosure同时服务多个深度但必须标明主要读者。契约的意图是先问读者问题再定内容而不是先列组件清单。叙事模型从问题到技术锚点写作标准定义了推荐的八步叙事推进可依主题调整顺序Problem什么读者/系统问题使该主题重要Intuition最简单正确的心理模型Concrete scenario一个可贯穿全文的代表性示例Mechanism涉及的组件、时序、数据与状态Boundaries职责、非职责与接口Failure behavior预期失败、恢复、部分成功与不可恢复情形Trade-offs收益、代价、替代方案与重新评估条件Technical anchors代码地图、schema、API、测试、遥测或运维信号。规则强调Do not force this order when another narrative answers the core question more clearly. Do not start with a flat list of services unless the documents question is specifically about inventory or ownership.四层解释法对于文中的每个核心概念标准要求提供足够多的以下层次以防止误解Intuition用平实语言说明含义Scenario系统为什么需要它Mechanism内部如何工作Boundary它不代表什么、不拥有什么。同时要求在使用术语前先定义优先使用一个稳定术语而非为变化而换用同义词。在 skills/maka-architecture-docs/references/bilingual-standard.md 中同样强调Use stable terms因为术语漂移会同时破坏可读性与双语语义对等。生命周期状态分离Current 与 Planned 不能混写这是整个方法论中最严格的不可谈判规则之一。写作标准定义了五个状态状态含义Current已在当前系统中验证Planned已达成一致但尚未完整实现的方向Deprecated仍存在但正在被移除或替换Exploratory讨论中的选项不隐含承诺Historical仅保留以解释过去的选择或迁移背景规则明确当文档中同时出现当前行为与未来设计时仅在文档级标注状态是不够的必须在主张或小节级别标注Label mixed-status sections at the claim or subsection level。同时绝不允许把未经验证的设计假设当作当前实现书写Never present an unverified design assumption as current implementation。仓库中的实际文档严格执行了这一纪律。例如 docs/architecture/runtime-resume-architecture.md 开篇就逐条声明Phases 0–2 are implemented.Phase 3A recovery-fact atomic write authority and the Resolver are implemented.The production Phase 3 reconciler, file evidence, and complete host-owner lifecycle remain future work.Phase 4 Git checkpoints, isolated restore, and durable rebaseline are not implemented.并补充Roadmap documents describe targets. Code and contract tests remain the authority for current behavior. This chapter always separates implemented behavior from planned work.——这是对实现状态必须与计划状态分离的直接示范。状态、不变量、边界、失败与恢复模板要求每个机制必须讲清楚四类事实这也是质量门禁quality-gate.md中的 Required 检查项状态与不变量当行为依赖生命周期或并发时必须写明状态及合法转换、每次转换的所有权、持久与易失状态、必须保持为真的不变量、幂等性/排序预期、中断/重试/超时/取消行为。边界该机制拥有什么、委托什么、明确不保证什么——Responsibilities and non-responsibilities are clear是 Required 项。失败与恢复覆盖有意义的失败路径、中断与恢复行为而非只讲 happy path。证据等级写作标准定义了证据强度排序必须使用可用的最强证据运行时行为或通过的测试实现与 schema已接受的 ADR 或规范设计讨论或路线图作者推断必须标注为推断。如果代码与文字矛盾应报告差异而非默默选择更顺口的说法。决策与权衡不只讲为什么这样对于有意义的工程选择标准要求记录背景与约束、所选方案、可信替代方案、选择理由、收益与代价、应触发重新评估的条件。对于长期存在且影响深远的决策当仓库使用 ADR 时应将其提升为 ADR文章可以摘要并链接到该决策。仓库的 docs/architecture 目录中即有大量 ADR 文件如*-adr*.md、*-v1.zh-CN.md可供链接而非在文章内复制全部细节。双语标准各自完整、语义对等Maka 的双语文档默认发布模型bilingual-standard.md是维护各自完整的中文版与英文版而非逐段穿插翻译对照版本使用相同相对路径、文件名或共享的稳定doc_id图、代码片段、schema 等语言中立资产复用共享对照版本是为目标语言读者进行的改编不是逐句转写transliteration。两个版本必须共同保留核心问题与范围、技术主张及其生命周期状态、确定性程度、示例与标识符、图语义、决策理由与权衡、警告/局限/失败行为。语义对等检查semantic parity checks列出了八项对照标题与摘要是否承诺相同答案、范围与排除是否匹配、状态标签是否等效、MUST/SHOULD/MAY 与保证的强度是否一致、数量/超时/限制/状态名/排序规则是否一致、失败与恢复行为是否同样完整、图术语是否被双方识别、链接是否解析到正确的语言版本。翻译不得把may变成will、把planned变成supported、把usually变成always——任何方向都不允许。术语表建议至少包含五列中文术语、英文规范术语、代码标识符相关时的拼写、语言中立的概念边界定义、应避免的歧义/废弃同义词。产品名、协议名、类型名、标识符不做翻译仅保留原文。质量门禁发布前检查清单quality-gate.md 在定稿前逐项检查其中标为Required的项在适用时是发布阻断项开篇陈述核心问题及其重要性无需通读全文即可推断目标读者与范围当前实现与 Planned/Exploratory/Deprecated/Historical 材料分离重要实现主张已对照适当证据核验或显式标注为未核验职责与非职责清晰覆盖有意义的失败路径、中断与恢复行为说明相关状态、转换、不变量、排序与幂等规则重要设计选择包含替代方案、代价与重新评估条件提供文章承诺深度所需的代码、接口、schema、测试或可观测性锚点每张图回答一个具体问题图术语与正文/实现术语一致说明阅读方向与重要省略双语版本在范围、生命周期状态、确定性、保证、局限上对等数字/限制/状态/排序/示例/失败行为一致规范术语与代码标识符一致遵循仓库布局与元数据约定记录所有权与核验日期避免脆弱的行号引用与重复。交付handoff时需报告创建/修改的文件、用于核验当前行为的证据、仍属计划或不确定的主张、双语版本是否通过语义对等评审、以及哪些清单项有意保持开放及原因。如何在仓库中实际应用这套模板将模板落地的完整流程由 skills/maka-architecture-docs/SKILL.md 定义共六步确立文章契约声明一个核心问题、目标读者、预期阅读深度、源语言与主张的实现状态收集证据在把实现细节当作事实呈现前检视相关代码路径、测试、schema、配置、ADR 与既有文档将已验证行为与计划/解释分开构建叙事从问题与直觉走向具体场景再到机制、边界、失败与权衡只保留有助于回答核心问题的章节添加技术锚点将主张连接到真实组件、状态转换、不变量、接口、可观测性信号或代码位置创建双语对照在保留概念、状态、示例、图与章节同一性的同时为目标语言自然重写运行质量门禁对照 quality-gate.md 评审两个语言版本在标记文档完成前修复失败的 Required 项。SKILL 还定义了五种任务模式Draft从代码/设计笔记/访谈/简报新建文档、Rewrite在保留技术含义的前提下改进既有文档、Translate生成自然的另一种语言版本、Review找出清晰度、证据、正确性、双语一致性方面的具体缺口、Standardize在不强制套用同一叙事的前提下统一术语、元数据、状态标签与结构。评审环节按影响排序给出可操作结论并尽可能引用精确章节或行号检查顺序为① 事实正确性与状态混淆② 缺失的边界、不变量或失败行为③ 断裂的叙事或未解释的概念④ 双语语义漂移与术语不一致⑤ 可维护性问题重复图、不稳定的代码引用⑥ 风格润色。该 Skill 还提供了 Agent 接口定义 skills/maka-architecture-docs/agents/openai.yaml其中声明display_name: Maka Architecture Docs、default_prompt: Use $maka-architecture-docs to draft or review a bilingual Maka backend architecture document.表明这套方法论可被 Agent 以 skill 形式调用。模板在仓库中的真实应用案例docs/architecture目录下已有多个文档实际采用了该模板结构可验证其可行性与组织效果docs/architecture/runtime-resume-architecture.mdResume Is Not Retry以模型调用工具时进程崩溃重启后如何区分已完成、未派发、未知、停放与损坏状态为核心问题用一次被中断的文件写入作为贯穿示例依次展开恢复流程心智模型、Phases 0–4 状态与不变量、边界、失败与恢复、决策权衡与实施顺序。其双语对照为 runtime-resume-architecture.zh-CN.md。docs/architecture/runtime-core-architecture-draft.mdLog Is the Runtime围绕Runtime Event Log 是 agent 交互的语义事实来源、系统状态是对有序日志的投影这一核心结论用State(t) Project(RuntimeEvents[0..t], policy, runtime configuration)展开并区分了 Model History Projector、Runtime Read Model、Terminal Fact Classifier、recovery 等不同消费者对同一日志的不同投影。其双语对照为 runtime-core-architecture-draft.zh-CN.md。docs/architecture/agent-graph-stream-scheduling-draft.md同样遵循章节骨架与状态标注约定。这些案例展示了模板的两种典型产出document_status: stable的当前权威文档标注核验日期与实现范围以及document_status: draft的演进中文档同样显式分离 Current 与未来设计。已知局限与未来方向从模板与配套标准自身来看有以下需要注意的边界以仓库现状为准模板是脚手架而非目录它不提供主题清单也不会替你决定信息架构若用户没有要求固定主题列表Skill 明确不强制套用固定主题清单。图是语言中立的共享资产双语文档共享同一套图与术语这要求图内用词必须能被两种语言版本识别必要时需在图外补充说明。元数据是可选约定bilingual-standard.md 明确Metadata is optional unless the project adopts it; semantic clarity is mandatory——语义清晰是强制的元数据遵循仓库既有约定无约定时才推荐而非擅自新建全仓结构。模板本身仍在演进它作为 Maka 架构文档体系的一部分随docs/architecture中实际文档的核验日期如last_verified: 2026-09-02持续接受事实核对任何已实现声明都以代码与契约测试为准。Further reading写作标准全文skills/maka-architecture-docs/references/writing-standard.md双语标准全文skills/maka-architecture-docs/references/bilingual-standard.md质量门禁清单skills/maka-architecture-docs/references/quality-gate.mdSkill 工作流与规则skills/maka-architecture-docs/SKILL.md模板正文skills/maka-architecture-docs/assets/article-template.md模板实际应用的英文/中文对照案例docs/architecture/runtime-resume-architecture.md 与 docs/architecture/runtime-resume-architecture.zh-CN.md、docs/architecture/runtime-core-architecture-draft.md 与 docs/architecture/runtime-core-architecture-draft.zh-CN.md、docs/architecture/agent-graph-stream-scheduling-draft.md更多架构决策与运行时文档docs/architecture【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Maka 架构文档写作方法论：用 article-template 写出一篇既易读又精确的双语架构文章
Maka 架构文档写作方法论用 article-template 写出一篇既易读又精确的双语架构文章【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文围绕 skills/maka-architecture-docs/assets/article-template.md 展开系统讲解 MakaApache Maka, Incubating沉淀下来的架构文档写作模板与配套方法论从 Frontmatter 元数据、十一节叙事骨架到文章契约、四层解释、生命周期状态分离、双语语义对等与质量门禁。读完本文你可以直接使用这套模板为 Maka Runtime 的任何组件或机制写出像技术博客一样易读、又保持架构记录级精确的双语架构文章并知道如何用仓库中的源码、测试、ADR 作为证据锚点。为什么需要一套架构文档模板Agent 运行时Runtime的架构文档面临一对天然矛盾可进入性新工程师能快速读懂与精确性实现细节、状态机、失败路径不能含糊。Maka 团队在长期维护运行时文档后发现常见文档存在几类结构性问题从服务清单或组件清单开篇读者记住了名词却不知道系统解决什么问题把 Planned计划中行为当作 Current已实现行为书写误导后续维护者只讲 happy path回避超时、中断、取消、部分成功等真实失败路径中英文版本逐句直译语义漂移后中文版和英文版承诺了不同的结论。article-template.md正是为此设计的一个写作起点脚手架starting scaffold而不是强制性的目录清单。它的定位在 skills/maka-architecture-docs/SKILL.md 中有明确说明Useassets/article-template.mdas a starting scaffold only when it fits the chosen subject; remove irrelevant sections rather than filling them mechanically.即模板服务于主题而非主题服务于模板不相关的章节应删除而不是机械填满。模板全景元数据与章节骨架模板由两部分组成YAML Frontmatter元数据和 Markdown 章节骨架。以下是模板的实际结构摘自 article-template.md。Frontmatter 元数据字段字段取值示例含义doc_idarchitecture.subject文档稳定 ID用于双语对照与跨文档引用titleReader-oriented title面向读者的标题而非组件名languagezh-CN/en本文语言source_languagezh-CN/en源语言用于翻译周期管理counterpart./counterpart-filename.md对应语言版本的相对路径implementation_statuscurrent/planned/exploratory/deprecated/historical所述行为在系统中的实现状态document_statusdraft/stable/deprecated/historical文档自身的成熟度状态translation_statussynced/needs-update/source-only双语同步状态last_verifiedYYYY-MM-DD最后核验日期ownersmaka-backend文档责任人这套元数据在仓库的docs/architecture目录中已被实际采用。例如 docs/architecture/runtime-resume-architecture.md 的 Frontmatter 写着doc_id: architecture.runtime-resume、implementation_status: phase_0_2_and_phase_3a_authority_current、translation_status: synced、last_verified: 2026-09-02、owners: [maka-backend]其双语对照版本 docs/architecture/runtime-resume-architecture.zh-CN.md 也遵循相同约定。十一节章节骨架模板建议的章节顺序与每个章节的写作提示如下# Reader-oriented title面向读者的标题。开头摘要blockquoteIn one paragraph: what question this article answers, the conclusion, and why it matters.——用一段话回答这篇文章回答什么问题、结论是什么、为什么重要。Why this matters描述工程问题或读者问题明确范围与相关排除项scope and relevant exclusions。Mental model给出最简单且正确的直觉在依赖任何术语前先定义它。A concrete scenario引入一个贯穿全文的代表性示例。How it works解释机制、时序、数据与组件职责只添加能回答具体问题的图。State and invariants描述生命周期、持久/易失状态、合法转换、所有权、排序与必须保持为真的条件。Boundaries明确该机制拥有什么、委托什么、明确不保证什么。Failure and recovery覆盖超时、中断、取消、重试、部分成功、恢复与不可恢复失败。Decisions and trade-offs解释所选设计、可信替代方案、收益、代价与重新评估条件。Code and operational map指向稳定模块、类型、接口、schema、测试、日志、trace 与 metrics匹配承诺的阅读深度。Known limitations and future direction将 Current、Planned、Exploratory 的主张显式分开。Further reading链接相关的架构文档、ADR、API 规范与代码自有引用。模板末尾有一句重要注释Remove any section that does not help answer this articles core question.——这是整个模板的运作原则结构围绕核心问题裁剪。写作契约动笔前先定六件事skills/maka-architecture-docs/references/writing-standard.md 要求动笔前先确立文章契约article contractCore question本文必须回答的唯一问题Audience新人、活跃开发者、技术负责人、外部集成方或有意组合Reading depth导向orientation、工作理解working understanding或实现/调试深度implementation/debugging depthScope覆盖什么、明确不覆盖什么Evidence basis代码、测试、schema、运行时观测、已接受的决策或提案Lifecycle statusCurrent / Planned / Exploratory / Deprecated / Historical。一篇文档可以通过渐进披露progressive disclosure同时服务多个深度但必须标明主要读者。契约的意图是先问读者问题再定内容而不是先列组件清单。叙事模型从问题到技术锚点写作标准定义了推荐的八步叙事推进可依主题调整顺序Problem什么读者/系统问题使该主题重要Intuition最简单正确的心理模型Concrete scenario一个可贯穿全文的代表性示例Mechanism涉及的组件、时序、数据与状态Boundaries职责、非职责与接口Failure behavior预期失败、恢复、部分成功与不可恢复情形Trade-offs收益、代价、替代方案与重新评估条件Technical anchors代码地图、schema、API、测试、遥测或运维信号。规则强调Do not force this order when another narrative answers the core question more clearly. Do not start with a flat list of services unless the documents question is specifically about inventory or ownership.四层解释法对于文中的每个核心概念标准要求提供足够多的以下层次以防止误解Intuition用平实语言说明含义Scenario系统为什么需要它Mechanism内部如何工作Boundary它不代表什么、不拥有什么。同时要求在使用术语前先定义优先使用一个稳定术语而非为变化而换用同义词。在 skills/maka-architecture-docs/references/bilingual-standard.md 中同样强调Use stable terms因为术语漂移会同时破坏可读性与双语语义对等。生命周期状态分离Current 与 Planned 不能混写这是整个方法论中最严格的不可谈判规则之一。写作标准定义了五个状态状态含义Current已在当前系统中验证Planned已达成一致但尚未完整实现的方向Deprecated仍存在但正在被移除或替换Exploratory讨论中的选项不隐含承诺Historical仅保留以解释过去的选择或迁移背景规则明确当文档中同时出现当前行为与未来设计时仅在文档级标注状态是不够的必须在主张或小节级别标注Label mixed-status sections at the claim or subsection level。同时绝不允许把未经验证的设计假设当作当前实现书写Never present an unverified design assumption as current implementation。仓库中的实际文档严格执行了这一纪律。例如 docs/architecture/runtime-resume-architecture.md 开篇就逐条声明Phases 0–2 are implemented.Phase 3A recovery-fact atomic write authority and the Resolver are implemented.The production Phase 3 reconciler, file evidence, and complete host-owner lifecycle remain future work.Phase 4 Git checkpoints, isolated restore, and durable rebaseline are not implemented.并补充Roadmap documents describe targets. Code and contract tests remain the authority for current behavior. This chapter always separates implemented behavior from planned work.——这是对实现状态必须与计划状态分离的直接示范。状态、不变量、边界、失败与恢复模板要求每个机制必须讲清楚四类事实这也是质量门禁quality-gate.md中的 Required 检查项状态与不变量当行为依赖生命周期或并发时必须写明状态及合法转换、每次转换的所有权、持久与易失状态、必须保持为真的不变量、幂等性/排序预期、中断/重试/超时/取消行为。边界该机制拥有什么、委托什么、明确不保证什么——Responsibilities and non-responsibilities are clear是 Required 项。失败与恢复覆盖有意义的失败路径、中断与恢复行为而非只讲 happy path。证据等级写作标准定义了证据强度排序必须使用可用的最强证据运行时行为或通过的测试实现与 schema已接受的 ADR 或规范设计讨论或路线图作者推断必须标注为推断。如果代码与文字矛盾应报告差异而非默默选择更顺口的说法。决策与权衡不只讲为什么这样对于有意义的工程选择标准要求记录背景与约束、所选方案、可信替代方案、选择理由、收益与代价、应触发重新评估的条件。对于长期存在且影响深远的决策当仓库使用 ADR 时应将其提升为 ADR文章可以摘要并链接到该决策。仓库的 docs/architecture 目录中即有大量 ADR 文件如*-adr*.md、*-v1.zh-CN.md可供链接而非在文章内复制全部细节。双语标准各自完整、语义对等Maka 的双语文档默认发布模型bilingual-standard.md是维护各自完整的中文版与英文版而非逐段穿插翻译对照版本使用相同相对路径、文件名或共享的稳定doc_id图、代码片段、schema 等语言中立资产复用共享对照版本是为目标语言读者进行的改编不是逐句转写transliteration。两个版本必须共同保留核心问题与范围、技术主张及其生命周期状态、确定性程度、示例与标识符、图语义、决策理由与权衡、警告/局限/失败行为。语义对等检查semantic parity checks列出了八项对照标题与摘要是否承诺相同答案、范围与排除是否匹配、状态标签是否等效、MUST/SHOULD/MAY 与保证的强度是否一致、数量/超时/限制/状态名/排序规则是否一致、失败与恢复行为是否同样完整、图术语是否被双方识别、链接是否解析到正确的语言版本。翻译不得把may变成will、把planned变成supported、把usually变成always——任何方向都不允许。术语表建议至少包含五列中文术语、英文规范术语、代码标识符相关时的拼写、语言中立的概念边界定义、应避免的歧义/废弃同义词。产品名、协议名、类型名、标识符不做翻译仅保留原文。质量门禁发布前检查清单quality-gate.md 在定稿前逐项检查其中标为Required的项在适用时是发布阻断项开篇陈述核心问题及其重要性无需通读全文即可推断目标读者与范围当前实现与 Planned/Exploratory/Deprecated/Historical 材料分离重要实现主张已对照适当证据核验或显式标注为未核验职责与非职责清晰覆盖有意义的失败路径、中断与恢复行为说明相关状态、转换、不变量、排序与幂等规则重要设计选择包含替代方案、代价与重新评估条件提供文章承诺深度所需的代码、接口、schema、测试或可观测性锚点每张图回答一个具体问题图术语与正文/实现术语一致说明阅读方向与重要省略双语版本在范围、生命周期状态、确定性、保证、局限上对等数字/限制/状态/排序/示例/失败行为一致规范术语与代码标识符一致遵循仓库布局与元数据约定记录所有权与核验日期避免脆弱的行号引用与重复。交付handoff时需报告创建/修改的文件、用于核验当前行为的证据、仍属计划或不确定的主张、双语版本是否通过语义对等评审、以及哪些清单项有意保持开放及原因。如何在仓库中实际应用这套模板将模板落地的完整流程由 skills/maka-architecture-docs/SKILL.md 定义共六步确立文章契约声明一个核心问题、目标读者、预期阅读深度、源语言与主张的实现状态收集证据在把实现细节当作事实呈现前检视相关代码路径、测试、schema、配置、ADR 与既有文档将已验证行为与计划/解释分开构建叙事从问题与直觉走向具体场景再到机制、边界、失败与权衡只保留有助于回答核心问题的章节添加技术锚点将主张连接到真实组件、状态转换、不变量、接口、可观测性信号或代码位置创建双语对照在保留概念、状态、示例、图与章节同一性的同时为目标语言自然重写运行质量门禁对照 quality-gate.md 评审两个语言版本在标记文档完成前修复失败的 Required 项。SKILL 还定义了五种任务模式Draft从代码/设计笔记/访谈/简报新建文档、Rewrite在保留技术含义的前提下改进既有文档、Translate生成自然的另一种语言版本、Review找出清晰度、证据、正确性、双语一致性方面的具体缺口、Standardize在不强制套用同一叙事的前提下统一术语、元数据、状态标签与结构。评审环节按影响排序给出可操作结论并尽可能引用精确章节或行号检查顺序为① 事实正确性与状态混淆② 缺失的边界、不变量或失败行为③ 断裂的叙事或未解释的概念④ 双语语义漂移与术语不一致⑤ 可维护性问题重复图、不稳定的代码引用⑥ 风格润色。该 Skill 还提供了 Agent 接口定义 skills/maka-architecture-docs/agents/openai.yaml其中声明display_name: Maka Architecture Docs、default_prompt: Use $maka-architecture-docs to draft or review a bilingual Maka backend architecture document.表明这套方法论可被 Agent 以 skill 形式调用。模板在仓库中的真实应用案例docs/architecture目录下已有多个文档实际采用了该模板结构可验证其可行性与组织效果docs/architecture/runtime-resume-architecture.mdResume Is Not Retry以模型调用工具时进程崩溃重启后如何区分已完成、未派发、未知、停放与损坏状态为核心问题用一次被中断的文件写入作为贯穿示例依次展开恢复流程心智模型、Phases 0–4 状态与不变量、边界、失败与恢复、决策权衡与实施顺序。其双语对照为 runtime-resume-architecture.zh-CN.md。docs/architecture/runtime-core-architecture-draft.mdLog Is the Runtime围绕Runtime Event Log 是 agent 交互的语义事实来源、系统状态是对有序日志的投影这一核心结论用State(t) Project(RuntimeEvents[0..t], policy, runtime configuration)展开并区分了 Model History Projector、Runtime Read Model、Terminal Fact Classifier、recovery 等不同消费者对同一日志的不同投影。其双语对照为 runtime-core-architecture-draft.zh-CN.md。docs/architecture/agent-graph-stream-scheduling-draft.md同样遵循章节骨架与状态标注约定。这些案例展示了模板的两种典型产出document_status: stable的当前权威文档标注核验日期与实现范围以及document_status: draft的演进中文档同样显式分离 Current 与未来设计。已知局限与未来方向从模板与配套标准自身来看有以下需要注意的边界以仓库现状为准模板是脚手架而非目录它不提供主题清单也不会替你决定信息架构若用户没有要求固定主题列表Skill 明确不强制套用固定主题清单。图是语言中立的共享资产双语文档共享同一套图与术语这要求图内用词必须能被两种语言版本识别必要时需在图外补充说明。元数据是可选约定bilingual-standard.md 明确Metadata is optional unless the project adopts it; semantic clarity is mandatory——语义清晰是强制的元数据遵循仓库既有约定无约定时才推荐而非擅自新建全仓结构。模板本身仍在演进它作为 Maka 架构文档体系的一部分随docs/architecture中实际文档的核验日期如last_verified: 2026-09-02持续接受事实核对任何已实现声明都以代码与契约测试为准。Further reading写作标准全文skills/maka-architecture-docs/references/writing-standard.md双语标准全文skills/maka-architecture-docs/references/bilingual-standard.md质量门禁清单skills/maka-architecture-docs/references/quality-gate.mdSkill 工作流与规则skills/maka-architecture-docs/SKILL.md模板正文skills/maka-architecture-docs/assets/article-template.md模板实际应用的英文/中文对照案例docs/architecture/runtime-resume-architecture.md 与 docs/architecture/runtime-resume-architecture.zh-CN.md、docs/architecture/runtime-core-architecture-draft.md 与 docs/architecture/runtime-core-architecture-draft.zh-CN.md、docs/architecture/agent-graph-stream-scheduling-draft.md更多架构决策与运行时文档docs/architecture【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考