| name | ai-friendly-architecture |
| source | ../../../../skills/ai-friendly-architecture/SKILL.md |
| source_version | 1.0.0 |
| translation_version | 1.0.0 |
| last_synced | "2026-02-05T00:00:00.000Z" |
| status | current |
| scope | universal |
| description | [UDS] 設計 AI 友善架構，包含明確模式、分層文件和語義邊界 |
AI 友善架構指南
語言: English | 繁體中文
版本: 1.0.0
最後更新: 2026-01-25
適用範圍: Claude Code Skills
核心標準: 本技能實作 AI 友善架構。完整方法論文件請參閱核心標準。
目的
本技能協助設計專案架構，透過明確模式、分層文件和語義邊界，最大化 AI 協作效能。
快速參考
核心原則
| 原則 | 描述 | 效益 |
|---|
| 明確優於隱含 | 明確記錄行為 | AI 無需猜測即可理解 |
| 分層上下文 | 多層級文件 | 依任務提供適當細節 |
| 語義邊界 | 清晰的模組邊界 | 獨立分析 |
| 可發現結構 | 自我說明的結構 | 快速定位 |
上下文層級
| 層級 | Token 預算 | 內容 |
|---|
| L1: 快速參考 | < 500 | 單行說明、API 簽章、入口點 |
| L2: 詳細 | < 5,000 | 完整 API 文件、使用範例 |
| L3: 範例 | 無限制 | 完整實作、邊界案例 |
建議結構
project/
├── .ai-context.yaml # AI 上下文配置
├── docs/
│ ├── QUICK-REF.md # 第 1 層文件
│ └── ARCHITECTURE.md # 第 2 層文件
├── src/
│ └── auth/
│ ├── index.ts # 入口點與模組標頭
│ ├── QUICK-REF.md # 模組快速參考
│ └── README.md # 模組文件
└── CLAUDE.md # AI 指令檔案
模組標頭範本
詳細指南
完整標準請參閱：
AI 優化格式（Token 效率）
AI 助手可使用 YAML 格式檔案以減少 Token 使用：
- 基礎標準：
ai/standards/ai-friendly-architecture.ai.yaml
.ai-context.yaml 配置
version: 1.0.0
project:
name: my-project
type: web-app
primary-language: typescript
modules:
- name: auth
path: src/auth/
entry: index.ts
description: 驗證與授權
dependencies: [database, crypto]
priority: high
- name: api
path: src/api/
entry: routes.ts
description: REST API 端點
dependencies: [auth, database]
priority: high
analysis-hints:
entry-points:
- src/main.ts
- src/index.ts
ignore-patterns:
- node_modules
- dist
- "*.test.ts"
上下文優先順序指南
| 優先級 | 內容類型 | 原因 |
|---|
| 1 | 入口點 | 應用程式結構 |
| 2 | .ai-context.yaml | 模組地圖和相依性 |
| 3 | QUICK-REF 檔案 | 快速 API 理解 |
| 4 | 修改的檔案 | 與任務直接相關 |
| 5 | 相依鏈 | 變更的上下文 |
應避免的反模式
| 反模式 | 問題 | 解決方案 |
|---|
| 魔術字串 | AI 無法追蹤常數 | 帶文件的型別常數 |
| 隱式路由 | 隱藏行為 | 明確路由映射 |
| 全域狀態 | 不可預測的相依性 | 依賴注入 |
| 循環相依 | 上下文混亂 | 階層式相依 |
| 單體檔案 | 上下文溢出 | 專注的模組 |
實作檢查清單
快速開始（< 1 小時）
標準實作（< 1 天）
配置偵測
本技能支援專案特定配置。
偵測順序
- 檢查是否存在
.ai-context.yaml
- 檢查是否存在
QUICK-REF.md 檔案
- 若未找到，建議建立 AI 友善結構
首次設定
若未找到配置：
- 建議：「此專案尚未為 AI 協作進行配置。是否要設定 AI 友善結構？」
- 建立
.ai-context.yaml 範本
- 在專案根目錄建立
QUICK-REF.md
相關標準
版本歷史
| 版本 | 日期 | 變更 |
|---|
| 1.0.0 | 2026-01-25 | 初始發布 |
授權
本技能以 CC BY 4.0 授權發布。
來源: universal-dev-standards
Next Steps Guidance | 下一步引導
After /ai-friendly-architecture completes, the AI assistant should suggest:
AI 友善架構指南已掌握。建議下一步 / AI-friendly architecture guide understood. Suggested next steps:
- 執行
/sdd 將 AI 友善架構設計納入正式規格 ⭐ Recommended / 推薦 — 確保架構決策有規格追蹤 / Ensure architecture decisions are tracked in specs
- 建立
.ai-context.yaml 和 QUICK-REF.md — 立即實作 AI 友善結構 / Implement AI-friendly structure immediately
- 執行
/ai-instruction-standards 更新 CLAUDE.md 以反映架構配置 — 讓 AI 指令檔案與架構保持同步 / Keep AI instruction files in sync with architecture
Related Standards
Version History
| Version | Date | Changes |
|---|
| 1.0.0 | 2026-01-25 | Initial release |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards
