Agent skill

Architecture Design

by devcodex-labs in devcodex-labs/devcodex

架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。

AGPL-3.0Auto-check passedDevelopment

Install Architecture Design

skills CLI
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install devcodex-labs/devcodex architecture-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .claude/skills && cp -r skills-src/content/skills/architecture-design .claude/skills/architecture-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
architecture-design
GitHub stars
439
Token cost
~1.1k tokens
SKILL.md length
198 words
Files
2
Skills in repo
70
Repo updated
First seen
Licence
AGPL-3.0

At a glance

架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。

  • Works in 8 steps: 结构化意图:提取目标、用户价值、业务角色、核心对象、范围、非目标、约束和待确认项。 → 建立主流程:用业务语言描述从触发到终态的主路径,先不落实现类名和数据库表。 → 拆分子流程:对复杂节点补子流程,明确入口、出口、失败分支和可恢复路径。 → …
  • Tasks that involve Architecture decision records
  • SKILL.md covers 目录导航, 定位, 触发条件 and 与领域架构 Skill 的关系, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Architecture Design is an agent skill from devcodex-labs/devcodex. 架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `intent.json`).

It sits in Development, covering Architecture decision records. The repository describes itself as: Intent-driven AI coding workflow runtime for consistent context, skills, approvals, validation, and handoffs across six AI coding hosts. The licence is AGPL-3.0.

When your agent uses it

  • Tasks that involve Architecture decision records

Example prompts

  • “/architecture-design”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. 结构化意图:提取目标、用户价值、业务角色、核心对象、范围、非目标、约束和待确认项。
  2. 建立主流程:用业务语言描述从触发到终态的主路径,先不落实现类名和数据库表。
  3. 拆分子流程:对复杂节点补子流程,明确入口、出口、失败分支和可恢复路径。
  4. 设计节点:逐个关键节点写职责、输入、输出、前置条件、状态变化、数据读写、外部依赖、成功/失败和幂等策略。
  5. 路由领域 Skill:按实际问题调用相关领域架构 Skill,引用其判断而不是重复发明领域规则。
  6. 建模与契约:在流程和节点稳定后,定义模块、数据模型、API/事件/CLI/Hook/MCP 契约和兼容策略。
  7. 写 ADR:记录会影响扩展性、复杂度、成本、风险或长期维护的关键决策。
  8. 完成落地:输出验证策略、风险、待确认项、任务拆分和 Architecture Review Checklist。

What it can do on your machine

Read from SKILL.md and the folder at commit 1dd4525. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Architecture Design loads about 1.1k tokens when it runs. Until then it costs about 30 tokens; SKILL.md has 198 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~30
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from devcodex-labs/devcodex at commit 1dd4525, republished under its AGPL-3.0 licence (© devcodex-labs). 198 words, ~1,064 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-design/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
architecture-design
description
架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。

Architecture Design Skill

目录导航

定位

本 Skill 负责完整架构设计文档的编排 Owner 视角。它把需求、业务流程、模块边界、数据模型、API 契约、一致性、异常补偿、ADR、验证与任务拆分组织成可直接指导开发、Review 和排期的设计产物。

本 Skill 不替代领域架构 Skill 的专业判断。它负责结构、顺序、追踪关系和交付物完整性;领域细节由后端、前端、数据、API、分布式、集成、平台、AI Agent、隐私合规、设计系统、DX 等 Skill 提供判断。

触发条件

场景是否触发
用户要求架构设计、系统设计、技术架构、概要设计、详细设计或可指导开发/Review/任务拆分的方案必须
需求从 0 到 1、跨模块、跨角色、跨状态、跨数据流或跨外部系统必须
方案需要主流程、子流程、节点设计、状态机、数据流、时序、ADR、风险和实施拆分必须
已有代码小修、单点 bug 修复、纯审计结论或只要求某一领域专家判断N/A + skipReason

与领域架构 Skill 的关系

领域主要协作 Skill本 Skill 的编排责任
业务与产品取舍product-strategy把业务目标、角色、对象和成功标准转成架构输入
后端领域与流程backend-domain-architecture确保业务不变量、权限、事务和幂等映射到节点设计
API 与公开契约api-contract-architecture确保 API 由流程和消费者反推,避免先写接口后补业务
数据模型与迁移data-architecture确保模型、查询、索引、生命周期和消费者闭环
前端体验frontend-architecture、ux-interaction-architecture确保状态、错误、加载、权限和交互与主流程一致
分布式与外部系统distributed-systems-architecture、external-integration-architecture确保失败、重试、补偿、超时和一致性边界可验证
平台、AI、合规与 DXplatform-ecosystem-architecture、ai-agent-system-architecture、privacy-compliance-architecture、developer-experience-architecture确保平台扩展、Agent 合同、合规边界和开发体验进入设计

核心门禁

Gate要求证据
ArchitectureDesignIntentGate先结构化需求目标、业务场景、角色、业务对象、边界和非目标requirementMatrix、boundary
BusinessFlowFirstGate先写主业务流程,再进入模块、类、表、API 或缓存mainFlow
FlowDecompositionGate复杂主流程节点必须拆成子流程,并说明触发、输入、输出和终止条件subFlows
NodeImplementationGate关键节点必须写职责、前置条件、读写数据、状态变化、依赖、成功/失败和幂等nodeDesign
StateMachineGate有状态对象必须写状态、事件、转移条件、终态和非法转移stateMachine
DataFlowSequenceGate数据流和时序必须说明谁产生、谁消费、何时持久化、何时可见dataFlow、sequence
ModuleBoundaryGate模块职责、依赖方向、共享契约和禁止跨层访问必须清楚moduleMap
DataModelConsistencyGate数据模型、唯一键、索引、事务、一致性、缓存和生命周期必须闭环dataModel、consistency
ApiContractMappingGateAPI/CLI/事件/Hook/MCP 契约必须由流程节点和消费者反推contractMatrix
FailureCompensationGate重试、超时、重复提交、部分成功、外部失败和人工修复路径必须定义failureMatrix
ArchitectureDecisionGate关键决策必须写问题、方案、理由、备选项、拒绝原因和代价ADR
DevelopmentTaskSplitGate最终任务拆分必须能映射回流程节点、模块、契约和验证项taskBreakdown
ArchitectureReviewChecklistGateReview 清单必须覆盖流程、状态、数据、契约、一致性、异常、可运维性和风险checklist

执行流程

  1. 结构化意图:提取目标、用户价值、业务角色、核心对象、范围、非目标、约束和待确认项。
  2. 建立主流程:用业务语言描述从触发到终态的主路径,先不落实现类名和数据库表。
  3. 拆分子流程:对复杂节点补子流程,明确入口、出口、失败分支和可恢复路径。
  4. 设计节点:逐个关键节点写职责、输入、输出、前置条件、状态变化、数据读写、外部依赖、成功/失败和幂等策略。
  5. 路由领域 Skill:按实际问题调用相关领域架构 Skill,引用其判断而不是重复发明领域规则。
  6. 建模与契约:在流程和节点稳定后,定义模块、数据模型、API/事件/CLI/Hook/MCP 契约和兼容策略。
  7. 写 ADR:记录会影响扩展性、复杂度、成本、风险或长期维护的关键决策。
  8. 完成落地:输出验证策略、风险、待确认项、任务拆分和 Architecture Review Checklist。

输出结构

架构设计文档必须包含 ## 目录导航。若某节不适用,保留标题并写明 N/A + skipReason;不要删除结构导致 Review 无法定位缺口。

markdown
## 目录导航
## 1. 架构目标与成功标准
## 2. 需求理解与业务场景
## 3. 角色、权限与核心业务对象
## 4. 系统边界与非目标
## 5. 当前上下文与约束
## 6. 整体架构图
## 7. 系统主流程
## 8. 子流程设计
## 9. 核心节点详细设计
## 10. 状态机设计
## 11. 数据流设计
## 12. 时序设计
## 13. 模块架构与依赖方向
## 14. 数据模型、索引与生命周期
## 15. API、事件、CLI、Hook 或 MCP 契约
## 16. 一致性、事务、缓存与幂等
## 17. 异常、重试、补偿与人工修复
## 18. 权限、安全、隐私与审计
## 19. 性能、容量与可扩展性
## 20. 可观测性与运维策略
## 21. ADR 决策记录
## 22. 风险、取舍与待确认项
## 23. 开发任务拆分与里程碑
## 24. Architecture Review Checklist

图表要求

  • 主流程优先使用 Mermaid flowchart TD,节点名称使用业务动作。
  • 有状态对象时使用 stateDiagram-v2 或状态转移表,必须包含非法转移处理。
  • 跨系统调用、异步事件、补偿和回调使用 sequenceDiagram 或时序表。
  • 图表必须和正文节点编号互相引用;不要为了形式完整添加无信息量图表。

反模式

反模式修正
从需求直接跳到 controller/service/repository/table/API先补主流程、子流程和节点设计
只说“使用 Redis/MQ/定时任务/缓存”但不说明业务触发与失败恢复补 ADR、数据可见性、一致性和补偿策略
流程图只有大框,没有关键节点的输入、输出、状态和数据读写补 NodeImplementationGate
API 先行,业务流程和消费者后补用 ApiContractMappingGate 反推契约
写“根据实际情况处理异常”明确失败矩阵、重试边界、人工修复和告警
为了显得完整引入不必要的分布式组件写取舍,证明必要性或删除该复杂度

完成判定

完成的架构设计必须回答:做什么、为什么做、谁参与、主流程怎么走、关键节点怎么实现、状态如何变化、数据如何流动、契约如何消费、失败如何恢复、一致性如何保证、替代方案为何不选、开发任务如何拆分、Review 如何验收。

© devcodex-labs, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in content/skills/architecture-design of devcodex-labs/devcodex.

  • SKILL.md
  • intent.json

Open the folder on GitHubat commit 1dd4525

Compare with similar skills

Architecture Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Architecture Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture Design this skilldevcodex-labs/devcodex439—~1.1kAutomated safety check: PassAGPL-3.0
PR Design DocOpenHands/OpenHands90k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3804 repos~2.4kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Domain Modelingbrim-borium/spotify_sdk1665 repos~806Automated safety check: PassApache-2.0
Design Doc MermaidSpillwaveSolutions/design-doc-mermaid1751 repos~5.6kAutomated safety check: PassNone

Similar skills

  • PR Design Doc

    OpenHands/OpenHands

    For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…

    90k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    380 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed
  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed
  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 5 repos~806 tokens
    DevelopmentAuto-check passed
  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    175 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed
  • Learning Opportunities

    DrCatHicks/learning-opportunities

    Facilitates deliberate skill development during AI-assisted coding.

    2.5k GitHub stars~2.5k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

More from devcodex-labs/devcodex

All 70 skills in this repo
  • Accessibility I18n

    devcodex-labs/devcodex

    无障碍与国际化专家 Owner — 当任务涉及可访问性、键盘操作、焦点、屏幕阅读器、ARIA、语言地区、本地化、RTL、翻译资源、用户可见文案或多语言文档时使用;要求把包容性体验和本地化验证绑定到真实用户路径。

    439 GitHub stars~718 tokensUpdated 20 days ago
    Auto-check passed
  • AI Agent System Architecture

    devcodex-labs/devcodex

    AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用;要求把 Agent 行为设计成可解释、可恢复、可审计。

    439 GitHub stars~2.4k tokensUpdated 20 days ago
    Auto-check passed
  • API Contract Architecture

    devcodex-labs/devcodex

    API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。

    439 GitHub stars~865 tokensUpdated 20 days ago
    Auto-check passed
  • Audit Common

    devcodex-labs/devcodex

    审查公共维度 G0~G5 + Profile Freshness Check — 所有 audit 子类型必先执行的基础维度层

    439 GitHub stars~4.1k tokensUpdated 20 days ago
    Auto-check passed
  • Audit Session

    devcodex-labs/devcodex

    审计工作流的跨会话状态机 — 在 <audit-root/.audit-state/<session-id.json 持久化轮次/发现项/收敛状态,支持 Token 中断后精准恢复

    439 GitHub stars~1.8k tokensUpdated 20 days ago
    Auto-check passed
  • Backend Domain Architecture

    devcodex-labs/devcodex

    后端领域架构专家 Owner — 当任务涉及领域模型、业务流程、权限、API、事务、一致性、幂等、兼容、数据边界、服务职责或用户要求从后端/领域专家角度审查时使用;要求用领域语言和业务不变量约束实现。

    439 GitHub stars~575 tokensUpdated 20 days ago
    Auto-check passed

Categories

Questions about Architecture Design

What does Architecture Design do?

架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。. Architecture Design is an agent skill from devcodex-labs/devcodex.

When should I use Architecture Design?

Architecture Design fits situations like: tasks that involve Architecture decision records.

How do I install Architecture Design in Claude Code?

Run `npx skills add devcodex-labs/devcodex --skill architecture-design -a claude-code`. Or copy the skill folder (content/skills/architecture-design in devcodex-labs/devcodex) into .claude/skills/architecture-design in your project. Claude Code loads it when a task matches its description.

How do I install Architecture Design in Codex?

Run `npx skills add devcodex-labs/devcodex --skill architecture-design -a codex`. Or copy the skill folder (content/skills/architecture-design in devcodex-labs/devcodex) into .agents/skills/architecture-design in your project. Codex loads it when a task matches its description.

Can I use Architecture Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add devcodex-labs/devcodex --skill architecture-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-design, .gemini/skills/architecture-design, .github/skills/architecture-design and .opencode/skills/architecture-design in your project.

What does Architecture Design need to run?

SKILL.md names no scripts, command-line tools or credentials: Architecture Design is instructions for the agent only.

Does Architecture Design access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Architecture Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Architecture Design use?

Architecture Design is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Architecture Design use?

About 1.1k tokens (SKILL.md is roughly 4.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Architecture Design?

Skills that share tags, products or a category with Architecture Design: PR Design Doc (OpenHands/OpenHands, 90k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 380 stars), Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars) and Domain Modeling (brim-borium/spotify_sdk, 166 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture Design?

devcodex-labs (a GitHub organization) maintains it in devcodex-labs/devcodex, which has 439 GitHub stars. The repository holds 70 skills in this directory. The repository was last updated on September 17, 2026.

Source: devcodex-labs/devcodex on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.