# 写作风格规范

## 核心原则

**段落式描述，层层递进，禁止清单罗列。**

## 禁止的写作模式

```markdown
<!-- 禁止：清单罗列 -->
### 模块列表
- 用户模块：处理用户相关功能
- 订单模块：处理订单相关功能
- 支付模块：处理支付相关功能

### 依赖关系
| 模块 | 依赖 | 说明 |
|------|------|------|
| A | B | xxx |
```

## 推荐的写作模式

```markdown
<!-- 推荐：段落式描述 -->
### 模块架构设计

系统采用分层模块化架构，核心业务逻辑围绕用户、订单、支付三大领域展开。
用户模块作为系统的入口层，承担身份认证与权限管理职责，为下游模块提供
统一的用户上下文。订单模块位于业务核心层，依赖用户模块获取会话信息，
并协调支付模块完成交易闭环。

值得注意的是，支付模块采用策略模式实现多渠道支付，通过接口抽象与
具体支付网关解耦。这一设计使得新增支付渠道时，仅需实现相应策略类，
无需修改核心订单逻辑，体现了开闭原则的应用。

从依赖方向分析，系统呈现清晰的单向依赖：表现层依赖业务层，业务层
依赖数据层，未发现循环依赖。这一架构特征确保了模块的独立可测试性，
同时为后续微服务拆分奠定了基础。
```

## 写作策略

### 策略一：主语转换

将主语从开发者视角转移到系统/代码本身：

| 禁止 | 推荐 |
|------|------|
| 我们设计了... | 系统采用... |
| 开发者实现了... | 该模块通过... |
| 代码中使用了... | 架构设计体现了... |

### 策略二：逻辑连接

使用连接词确保段落递进：

- **承接**：此外、进一步、在此基础上
- **转折**：然而、值得注意的是、不同于
- **因果**：因此、这一设计使得、由此可见
- **总结**：综上所述、从整体来看、概言之

### 策略三：深度阐释

每个技术点需包含：
1. **是什么**：客观描述技术实现
2. **为什么**：阐释设计意图和考量
3. **影响**：说明对系统的影响和价值

```markdown
<!-- 示例 -->
系统采用依赖注入模式管理组件生命周期（是什么）。这一选择源于
对可测试性和松耦合的追求（为什么）。通过将依赖关系外置于
配置层，各模块可独立进行单元测试，同时为运行时替换实现
提供了可能（影响）。
```

## 章节模板

### 架构概述（段落式）

```markdown
## 系统架构概述

{项目名称}采用{架构模式}架构，整体设计围绕{核心理念}展开。
从宏观视角审视，系统可划分为{N}个主要层次，各层职责明确，
边界清晰。

{表现层/入口层}作为系统与外部交互的唯一入口，承担请求解析、
参数校验、响应封装等职责。该层通过{框架/技术}实现，遵循
{设计原则}，确保接口的一致性与可维护性。

{业务层}是系统的核心所在，封装了全部业务逻辑。该层采用
{模式/策略}组织代码，将复杂业务拆解为{N}个领域模块。
值得注意的是，{关键设计决策}体现了对{质量属性}的重视。

{数据层}负责持久化与数据访问，通过{技术/框架}实现。
该层与业务层通过{接口/抽象}解耦，使得数据源的替换
不影响上层逻辑，体现了依赖倒置原则的应用。
```

### 设计模式分析（段落式）

```markdown
## 设计模式应用

代码库中可识别出{模式1}、{模式2}等设计模式的应用，
这些模式的选择与系统的{核心需求}密切相关。

{模式1}主要应用于{场景/模块}。具体实现位于
`{文件路径}`，通过{实现方式}达成{目标}。
这一模式的引入有效解决了{问题}，使得{效果}。

在{另一场景}中，系统采用{模式2}应对{挑战}。
不同于{模式1}的{特点}，{模式2}更侧重于{关注点}。
从`{文件路径}`的实现可以看出，设计者通过
{具体实现}实现了{目标}。

综合来看，模式的选择体现了对{原则}的遵循，
为系统的{质量属性}提供了有力支撑。
```

### 算法流程分析（段落式）

```markdown
## 核心算法设计

{算法名称}是系统处理{业务场景}的核心逻辑，
其实现位于`{文件路径}`。

从算法流程来看，整体可分为{N}个阶段。首先，
{第一阶段描述}，这一步骤的目的在于{目的}。
随后，算法进入{第二阶段}，通过{方法}实现{目标}。
最终，{结果处理}完成整个处理流程。

在复杂度方面，该算法的时间复杂度为{O(x)}，
空间复杂度为{O(y)}。这一复杂度特征源于
{原因}，在{数据规模}场景下表现良好。

值得关注的是，{算法名称}采用了{优化策略}，
相较于朴素实现，{具体优化点}。这一设计决策
使得{性能提升/效果}。
```

## 质量检查清单

- [ ] 无清单罗列（禁止 `-` 或 `|` 表格作为主体内容）
- [ ] 段落完整（每段 3-5 句，逻辑闭环）
- [ ] 逻辑递进（有连接词串联）
- [ ] 客观表达（无"我们"、"开发者"等主观主语）
- [ ] 深度阐释（包含是什么/为什么/影响）
- [ ] 代码引用（关键点附文件路径）
