architecture-cognition

📁 qiao-925/qiao-skills 📅 9 days ago
1
总安装量
1
周安装量
#41336
全站排名
安装命令
npx skills add https://github.com/qiao-925/qiao-skills --skill architecture-cognition

Agent 安装分布

windsurf 1
cursor 1
codex 1
claude-code 1

Skill 文档

全局架构认知规范

帮助 AI Agent 建立对系统的全局认知,避免局部优化导致全局问题。


⚠️ 核心强制要求

在修改任何代码前,必须理解该修改在整个系统中的位置、影响范围和依赖关系。

三层架构约束

  • 前端层 → 业务层 → 基础设施层(单向依赖)
  • 禁止反向依赖:基础设施层不能依赖业务层或前端层
  • 禁止跨层访问:前端层不能直接访问基础设施层

AI Agent 行为要求

修改代码前必须回答

  1. 位置识别:属于哪一层?影响哪些组件?有跨层依赖风险?
  2. 影响范围:影响哪些数据流?有组件依赖此接口?需更新测试?
  3. 架构约束:是否违反三层架构?是否引入循环依赖?

创建新组件时必须明确

  1. 职责定位:属于哪一层?单一职责是什么?与现有组件关系?
  2. 接口设计:需要抽象基类/Protocol?需要工厂模式?
  3. 依赖管理:依赖哪些组件?是否可依赖注入?是否违反依赖方向?

遇到以下情况必须升级给用户

  • 涉及跨层依赖的修改
  • 涉及核心组件接口变更
  • 涉及数据流向改变的修改
  • 涉及性能或资源消耗的重大变更

快速参考

层 核心组件 职责
前端层 frontend/main.py 用户交互、UI 展示
业务层 RAGService, QueryEngine 业务逻辑、流程编排
基础设施层 IndexManager, Embedding, LLM 技术实现、无业务逻辑

参考资料

  • references/system-overview.md – 系统定位与核心价值
  • references/three-layer-architecture.md – 三层架构详细说明与违规示例
  • references/component-map.md – 核心组件地图与依赖关系
  • references/data-flow.md – 查询流程与索引构建数据流