aif-architecture

架构 - 生成架构指南

生成 .ai-factory/ARCHITECTURE.md，其中包含适用于项目的架构决策。

工作流

步骤 0：加载配置和项目上下文

首先： 如果 .ai-factory/config.yaml 存在，请读取该文件以确定：

• 路径： paths.description 和 paths.architecture
• 语言： language.ui 用于提示词，language.artifacts 用于生成的架构内容

通过 /aif 调用时，假定 .ai-factory/config.yaml 已为当前设置流程写入，并且已包含解析后的 language.ui / language.artifacts 值。

如果 config.yaml 不存在，则使用默认值：

• DESCRIPTION.md：.ai-factory/DESCRIPTION.md
• ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
• 语言：en（英语）

然后： 如果 .ai-factory/DESCRIPTION.md 存在，请读取该文件（使用配置中的路径）以了解：

• 技术栈（语言、框架、数据库、ORM）
• 项目规模和复杂度
• 核心功能和需求
• 非功能性需求

如果 .ai-factory/DESCRIPTION.md 不存在：

⚠️  No project description found.

Run /aif first to set up project context, or describe your project manually:
- What are you building?
- Tech stack (language, framework, database)?
- Team size?
- Expected scale?

允许独立使用——如果用户提供了手动输入，请改用该输入。

读取 .ai-factory/skill-context/aif-architecture/SKILL.md——如果该文件存在，则必须读取。

此文件包含 /aif-evolve 根据补丁、代码库约定和技术栈分析积累的项目专属规则。这些规则针对当前项目量身定制。

如何应用 skill-context 规则：

• 将其视为对本技能通用说明的项目级覆盖规则
• 如果 skill-context 规则与本 SKILL.md 中的通用规则冲突，以 skill-context 规则为准（更具体的上下文优先——遵循与嵌套 CLAUDE.md 文件相同的原则）
• 如果不存在冲突，则同时应用两者：SKILL.md 中的通用规则和 skill-context 中的项目规则
• 即使 skill-context 规则看似与本技能的默认规则相矛盾，也不要忽略它们——这些规则的存在是因为项目经验证明默认规则并不够用
• 重要： skill-context 规则适用于本技能的所有输出，包括 ARCHITECTURE.md 模板。本 SKILL.md 中的模板是基础结构。如果 skill-context 规则指出“架构文档必须包含 X”或“必须涵盖 Y 部分”，则必须相应扩展模板。生成的 ARCHITECTURE.md 违反 skill-context 规则即为错误。

强制执行： 生成任何输出文件后，都要根据所有 skill-context 规则进行验证。如果违反任何规则，请在向用户展示前修正输出。

步骤 1：推荐架构

根据项目背景，参照决策矩阵进行评估并推荐架构：

如果 $ARGUMENTS 指定了架构（例如，/aif-architecture explicit）：

• 直接映射（无需后缀）：
  • layers → 分层架构
  • microservices → 微服务
  • structured → 结构化模块（询问变体，见下文）
  • explicit → 显式架构（询问变体，见下文）
• 旧版别名（已弃用，映射到当前模式——未来可能会移除）：
  • clean → 显式架构
  • ddd → 显式架构
  • monolith → 结构化模块
  • vertical → 显式架构（按实体划分的垂直切片）
• 带后缀（变体已确定，无需询问）：
  • structured-layers → 结构化模块（技术分层）
  • structured-vertical → 结构化模块（按实体划分的垂直切片）
  • explicit-layers → 显式架构（技术分层）
  • explicit-vertical → 显式架构（按实体划分的垂直切片）
  • explicit-flat → 显式架构（扁平垂直切片 - 简化版）
• 不带后缀（询问用户选择变体）：
  • 如果指定了 structured 但没有后缀，询问用户：“你更倾向于结构化模块的哪种文件夹结构变体？1. 技术分层（更简单）或 2. 按实体划分的垂直切片（更适合大型模块）”。等待用户回答后再生成产物。
  • 如果指定了 explicit 但没有后缀，询问用户：“你更倾向于显式架构的哪种文件夹结构变体？1. 技术分层，2. 显式架构（按实体划分的垂直切片），或 3. 显式架构（扁平垂直切片 - 简化版）”。等待用户回答后再生成产物。
• 直接使用已确定的架构，跳过推荐步骤并继续执行步骤 1.5

如果未请求特定架构：

• 根据决策矩阵评估项目（见 references/architecture.md）
• 考虑：团队规模、领域复杂度、规模要求、技术栈
• 通过 AskUserQuestion 提出建议：

Based on your project context:
- [reason 1 from project analysis]
- [reason 2 from project analysis]

Which architecture pattern should we use?

1. [Recommended pattern] (Recommended) — [why it fits]
2. [Alternative 1] — [brief reason]
3. [Alternative 2] — [brief reason]
4. [Alternative 3] — [brief reason]

架构选项：

• 结构化模块（技术分层）
• 结构化模块（按实体划分的垂直切片）
• 显式架构（技术分层）
• 显式架构（按实体划分的垂直切片）
• 显式架构（扁平垂直切片 - 简化版）
• 微服务
• 分层架构 （请参阅 references/architecture.md 中对这些模式的详细说明，以便拟定建议）。

关键指示： 生成 ARCHITECTURE.md 产物之前，必须阅读 references/architecture.md，确保术语和依赖方向正确。

步骤 1.5：代码库对齐检查

关键： 生成文档之前，将所选架构的理想文件夹结构（来自 references/architecture.md）与现有代码库结构进行比较。

• 如果项目为空或基本符合：继续执行步骤 2。
• 如果存在重大差异： 不要悄悄将理想架构与混乱的实际结构合并。必须停止，并通过 AskUserQuestion 询问用户如何继续：

The current project structure differs significantly from the ideal [Pattern Name] architecture.
[Briefly list 1-2 major differences]

How should we generate the ARCHITECTURE.md?
1. Adapt the guidelines to fit the existing application structure (document reality).
2. Generate the pure, strict architecture guidelines (requires refactoring the application later to match).

等待用户决定后再继续执行步骤 2。

步骤 2：生成架构文档

如有需要，为解析后的架构路径创建父目录。

按照以下结构生成解析后的架构文档（默认：.ai-factory/ARCHITECTURE.md），并根据项目的技术栈和语言进行调整：

# Architecture: [Pattern Name]

## Overview
[1-2 paragraphs: what this architecture is and why it was chosen for THIS project]

## Decision Rationale
- **Project type:** [from DESCRIPTION.md]
- **Tech stack:** [language, framework]
- **Key factor:** [primary reason for this choice]

## Folder Structure
\`\`\`
[folder structure adapted to the project's tech stack]
[use actual framework conventions — e.g., Next.js app/ dir, Laravel app/ dir, Go cmd/ dir]
\`\`\`

## Dependency Rules
[What depends on what. Inner vs outer layers. Module boundaries.]

- ✅ [allowed dependency direction]
- ❌ [forbidden dependency direction]

## Layer/Module Communication
[How layers or modules communicate with each other]
- [pattern 1]
- [pattern 2]

## Key Principles
1. [Principle 1 — adapted to this project]
2. [Principle 2]
3. [Principle 3]

[If the user chose Option 2 (strict architecture) in Step 1.5, add the following section:]
## Legacy vs New Code Policy
- **New Features:** All new code MUST strictly follow the architecture defined in this document.
- **Legacy Code Modification:** Do NOT automatically refactor unrelated legacy code to fit this architecture. Touch legacy code only when necessary for bug fixes, when tasked with explicit refactoring, or when adapting it to be consumed by new features.
- **Interoperability:** When new code must call legacy code, isolate the interaction using adapters, interfaces, or facades so that legacy patterns do not pollute the new architecture.

[If the user chose Option 1 (adapt to reality) in Step 1.5, add the following lighter section:]
## Code Organization Note
- **New Features:** All new code should follow the architecture defined in this document where practical.
- **Existing Code:** Document the current structure as-is. When modifying existing code, prefer following the architectural conventions in this document, but do not force a rewrite of unrelated code.
- **Interoperability:** When new code must call existing code, prefer clean interfaces but do not refactor purely for structural alignment.

## Code Examples

### [Example 1 title]
\`\`\`[language]
[code example in the project's language/framework]
\`\`\`

### [Example 2 title]
\`\`\`[language]
[code example showing dependency rule]
\`\`\`

## Anti-Patterns
- ❌ [What NOT to do in this architecture]
- ❌ [Common mistake to avoid]

生成规则：

• 根据项目使用的语言和框架调整所有示例（不要在 Go 项目中使用 TypeScript 示例）
• 遵循项目的实际约定（导入路径、命名等）
• 注重实用性，聚焦影响日常开发的规则
• 根据用户在步骤 1.5 中的决定构建生成的文件夹结构（根据实际情况调整，或采用严格的纯架构）。未经用户同意，不要自动合并两者。

步骤 3：更新 DESCRIPTION.md

如果解析后的 DESCRIPTION.md 路径存在，请在解析后的 language.artifacts 中添加或更新架构指向部分。 使用配置中的解析后架构路径，而非默认路径字面值。

## [Localized heading: Architecture]
[Localized sentence in resolved artifacts language referencing the resolved architecture artifact path for detailed architecture guidelines.]
[Localized label: Pattern]: [chosen pattern name]

步骤 4：更新 AGENTS.md

如果项目根目录中存在 AGENTS.md，请将解析后的架构文档路径添加到解析后的 language.artifacts 中本地化的“AI Context Files”表格：

| [resolved-architecture-path] | [Localized architecture artifact description in resolved artifacts language] |

仅当解析后的架构路径尚未存在时才添加。

步骤 5：确认

使用解析后的 language.ui 提示确认信息，并报告解析后的架构路径：

[Localized success heading in `language.ui`]

[Localized pattern label in `language.ui`]: [chosen pattern]
[Localized file label in `language.ui`]: [resolved architecture path]

[Localized key-rules heading in `language.ui`]:
- [rule 1]
- [rule 2]
- [rule 3]

[Localized closing sentence in `language.ui` about workflow skills following these architecture guidelines.]

文档所有权

• 主要归属：解析后的架构文档路径（默认：.ai-factory/ARCHITECTURE.md）。
• 遵循配置覆盖项：如 config.yaml 中提供了解析后的架构路径，则写入该路径。
• 允许的配套更新：解析后的 DESCRIPTION 路径（来自 config.yaml）中的架构指向，以及 AGENTS.md 上下文表格中的架构行。
• 只读上下文：路线图、规则、研究和计划文档，除非用户明确要求，否则不得修改。

---