1. Introduction
This is a skill used toorganize and consolidateproject knowledge.
During project development, we naturally form many design patterns, established conventions, or specific architectural choices. The goal of this skill is retrospective: to extract these design elements from existing code and discussions and organize them into clear documentation. It helps us maintain consistency in project concepts and makes it easier for new members (or our future selves) to understand the whole picture of the system.
2. When to Use
Use this skill in the following situations:
- Periodic review: When a relatively large feature module has been completed and its design approach needs to be summarized.
- Pattern consolidation: When a certain specific interaction pattern (such as a particular frontend-backend communication protocol) is found repeatedly appearing in the code and needs to be formally defined.
- Supplementing development logs: After recording a development log (
doc-todo-log-loop), when it is found that this update contains important architectural decisions worth extracting separately. - Clarifying thinking: When the project becomes complex and the overall structure or directory planning needs to be re-examined.
3. Procedure
Step 1: Review & Identify
Review recent code changes, file structure adjustments, or key conversation records. Consider the following questions:
- What core problem did we recently solve? What approach was used to solve it?
- Have new "standard practices" or "protocols" emerged in the code?
- Does the directory structure have a clear intent for hierarchical division?
Step 2: Extract Concepts
Abstract specific implementation details into general design concepts. Note: better to have less than too much; do not over-abstract or over-distill.
- Example: From a series of "modified files", extract "introduced a configuration-driven plugin mechanism".
- Example: From a series of "added a certain check on the frontend", extract "defined a streaming rendering protocol based on specific markers".
Step 3: Document
Use the template below to create or update the project's design documentation (usually stored in docs/ or in the root directory, such as ARCHITECTURE.md or DESIGN_CONCEPTS.md）。
- Keep the language plain and accurate.
- Record "why it is done this way" and "how it works".
4. Template
When organizing design documentation, please refer to the following structure. You can adjust it flexibly according to the actual situation.
# [项目/模块名称] 设计理念与架构规范
## 1. 核心理念 (Core Philosophy)
> 简述项目的核心设计原则。不仅仅是“做什么”，更重要的是“为什么这么做”。
* **原则 1**: [例如：文档驱动开发] - [简短解释]
* **原则 2**: [例如：UI 与逻辑分离] - [简短解释]
## 2. 关键概念 (Key Concepts)
> 定义项目中特定的术语、模型或隐喻。
* **[概念名]**: [解释。例如：“Inbox 范式” - 所有输入先进入 Inbox 目录等待分拣。]
* **[概念名]**: [解释。例如：“Agent 节点” - 图谱中的独立执行单元。]
## 3. 交互协议 (Interaction Protocols)
> 记录前后端交互、组件间通信的特定规则。
* **协议名称**: [例如：标记流式协议]
* **机制**: [描述协议如何工作]
* **目的**: [解决了什么问题]
## 4. 架构与目录意图 (Architecture & Directory Intent)
> 解释核心目录或模块的设计意图。
* `app/core`: [存放核心业务逻辑，不依赖具体 UI]
* `components/ui`: [纯展示组件，无业务状态]