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…
架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install devcodex-labs/devcodex architecture-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ 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-srcUse ~/.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/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .claude/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install devcodex-labs/devcodex architecture-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .agents/skills && cp -r skills-src/content/skills/architecture-design .agents/skills/architecture-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .agents/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install devcodex-labs/devcodex architecture-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/content/skills/architecture-design .cursor/skills/architecture-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .cursor/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/devcodex-labs/devcodex.git --path content/skills/architecture-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install devcodex-labs/devcodex architecture-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/content/skills/architecture-design .gemini/skills/architecture-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .gemini/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install devcodex-labs/devcodex architecture-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .github/skills && cp -r skills-src/content/skills/architecture-design .github/skills/architecture-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .github/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add devcodex-labs/devcodex --skill architecture-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install devcodex-labs/devcodex architecture-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/content/skills/architecture-design .opencode/skills/architecture-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "architecture-design" agent skill from https://github.com/devcodex-labs/devcodex/tree/main/content/skills/architecture-design into .opencode/skills/architecture-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "architecture-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
architecture-design架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。
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.
8 steps, taken from the first numbered list in SKILL.md.
Read from SKILL.md and the folder at commit 1dd4525. It shows what the files ask for, not the result of running them.
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.
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.
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
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.
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.
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.
The full file from devcodex-labs/devcodex at commit 1dd4525, republished under its AGPL-3.0 licence (© devcodex-labs). 198 words, ~1,064 tokens.
.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.本 Skill 负责完整架构设计文档的编排 Owner 视角。它把需求、业务流程、模块边界、数据模型、API 契约、一致性、异常补偿、ADR、验证与任务拆分组织成可直接指导开发、Review 和排期的设计产物。
本 Skill 不替代领域架构 Skill 的专业判断。它负责结构、顺序、追踪关系和交付物完整性;领域细节由后端、前端、数据、API、分布式、集成、平台、AI Agent、隐私合规、设计系统、DX 等 Skill 提供判断。
| 场景 | 是否触发 |
|---|---|
| 用户要求架构设计、系统设计、技术架构、概要设计、详细设计或可指导开发/Review/任务拆分的方案 | 必须 |
| 需求从 0 到 1、跨模块、跨角色、跨状态、跨数据流或跨外部系统 | 必须 |
| 方案需要主流程、子流程、节点设计、状态机、数据流、时序、ADR、风险和实施拆分 | 必须 |
| 已有代码小修、单点 bug 修复、纯审计结论或只要求某一领域专家判断 | N/A + skipReason |
| 领域 | 主要协作 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、合规与 DX | platform-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 |
ApiContractMappingGate | API/CLI/事件/Hook/MCP 契约必须由流程节点和消费者反推 | contractMatrix |
FailureCompensationGate | 重试、超时、重复提交、部分成功、外部失败和人工修复路径必须定义 | failureMatrix |
ArchitectureDecisionGate | 关键决策必须写问题、方案、理由、备选项、拒绝原因和代价 | ADR |
DevelopmentTaskSplitGate | 最终任务拆分必须能映射回流程节点、模块、契约和验证项 | taskBreakdown |
ArchitectureReviewChecklistGate | Review 清单必须覆盖流程、状态、数据、契约、一致性、异常、可运维性和风险 | checklist |
架构设计文档必须包含 ## 目录导航。若某节不适用,保留标题并写明 N/A + skipReason;不要删除结构导致 Review 无法定位缺口。
## 目录导航
## 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 Checklistflowchart 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
SKILL.md and 1 other file in content/skills/architecture-design of devcodex-labs/devcodex.
Open the folder on GitHubat commit 1dd4525
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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Architecture Design this skilldevcodex-labs/devcodex | 439 | — | ~1.1k | Automated safety check: Pass | AGPL-3.0 | |
| PR Design DocOpenHands/OpenHands | 90k | — | ~2.4k | Automated safety check: Pass | MIT | |
| Cto AdvisorIbrahim-3d/orchestrator-supaconductor | 380 | 4 repos | ~2.4k | Automated safety check: Pass | MIT | |
| Improve Codebase Architectureywwynm/EverythingDone | 144 | 15 repos | ~1.3k | Automated safety check: Pass | GPL-3.0 | |
| Domain Modelingbrim-borium/spotify_sdk | 166 | 5 repos | ~806 | Automated safety check: Pass | Apache-2.0 | |
| Design Doc MermaidSpillwaveSolutions/design-doc-mermaid | 175 | 1 repos | ~5.6k | Automated safety check: Pass | None |
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…
Ibrahim-3d/orchestrator-supaconductor
Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.
ywwynm/EverythingDone
Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.
brim-borium/spotify_sdk
Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.
SpillwaveSolutions/design-doc-mermaid
Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.
DrCatHicks/learning-opportunities
Facilitates deliberate skill development during AI-assisted coding.
devcodex-labs/devcodex
无障碍与国际化专家 Owner — 当任务涉及可访问性、键盘操作、焦点、屏幕阅读器、ARIA、语言地区、本地化、RTL、翻译资源、用户可见文案或多语言文档时使用;要求把包容性体验和本地化验证绑定到真实用户路径。
devcodex-labs/devcodex
AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用;要求把 Agent 行为设计成可解释、可恢复、可审计。
devcodex-labs/devcodex
API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。
devcodex-labs/devcodex
审查公共维度 G0~G5 + Profile Freshness Check — 所有 audit 子类型必先执行的基础维度层
devcodex-labs/devcodex
审计工作流的跨会话状态机 — 在 <audit-root/.audit-state/<session-id.json 持久化轮次/发现项/收敛状态,支持 Token 中断后精准恢复
devcodex-labs/devcodex
后端领域架构专家 Owner — 当任务涉及领域模型、业务流程、权限、API、事务、一致性、幂等、兼容、数据边界、服务职责或用户要求从后端/领域专家角度审查时使用;要求用领域语言和业务不变量约束实现。
Categories
架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。. Architecture Design is an agent skill from devcodex-labs/devcodex.
Architecture Design fits situations like: tasks that involve Architecture decision records.
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.
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.
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.
SKILL.md names no scripts, command-line tools or credentials: Architecture Design is instructions for the agent only.
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.
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.
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.
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.
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.
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.