name: planning-guidelines description: “Portfolio Buddy 2 开发的核心规划原则。在以下情况使用：规划任何功能实现、修改或重构。确保代码保留、移动/桌面端优化以及彻底的需求收集。”

Portfolio Buddy 2 规划指南

核心原则

在规划和实现 Portfolio Buddy 2 的功能时，始终遵循以下基本原则：

保留现有代码 - 默认选择扩展而非替换
为移动端和桌面端优化 - 每个功能必须在两者上都能良好工作
提出澄清性问题 - 在执行前收集完整上下文
无缝集成 - 新代码应感觉是现有代码库的原生部分

代码保留策略

默认行为：始终保留

规则： 除非明确指示进行重构或重写，否则保留现有代码。

当实现新功能或修复时：

✅ 扩展现有组件
✅ 在现有功能旁添加新函数
✅ 保留现有模式和约定
✅ 保持向后兼容性
❌ 不要仅仅因为“可以”就重构正常工作的代码
❌ 没有正当理由不要引入新模式

例外情况：显著更好的选项

仅当满足所有条件时，你可以提议改进现有代码：

风险极低 - 更改是孤立的、易于理解的、容易撤销的
收益巨大 - 带来显著好处（正确性、性能、可维护性）
不增加不必要的复杂性 - 解决方案更简单或复杂度相当
理由清晰 - 能够解释为何适用此例外

当适用例外时，你必须：

解释当前实现的问题
展示提议的改进
论证其为何满足所有三个标准
在实施前获得用户批准

真实示例：年化增长率修复

情况： 在实现交易日更新期间，发现年化增长率计算在数学上是错误的。

当前（错误）代码：

const tradingPeriodDays = uniqueTradingDates.size || 1;  // 150 天
const annualGrowthRate = (totalPnl / startingCapital / tradingPeriodDays) * 365 * 100;
// 结果：因混合交易日（分母）与日历日年化（365）而被夸大

为何适用例外：

风险极低 ✅

孤立计算（一行）
易于理解（日历日 vs 交易日）
如果错误，易于撤销

收益巨大 ✅

修复了错误的财务指标（准确性至关重要）
回报被夸大了约 2.4 倍
符合金融行业标准

不增加不必要的复杂性 ✅

增加了 9 行（日历日计算）
逻辑更清晰、更正确
没有新的依赖项

结果： 由于例外标准清晰满足，用户立即批准了修复。

移动端与桌面端优化

每个功能都必须针对移动端和桌面端体验进行优化。

快速参考清单

✅ 使用响应式 Tailwind 类

移动端基础样式（无前缀）
sm: 用于小屏幕（640px+）
md: 用于中屏幕（768px+）
lg: 用于大屏幕（1024px+）

✅ 触摸目标

所有交互元素的最小尺寸为 44x44 像素
使用 touch-manipulation CSS 类以获得更好的触摸响应

✅ 测试两种视口

在完成前验证布局在移动端和桌面端均有效
检查小屏幕上文本是否可读
确保按钮/输入框尺寸合适

应遵循的现有模式

Portfolio Buddy 2 已经拥有优秀的响应式模式。参考这些：

示例 1：响应式文本大小

className="text-xs sm:text-sm"        // 移动端更小
className="text-base sm:text-lg"      // 桌面端更大

示例 2：响应式间距

className="gap-1 sm:gap-2"           // 移动端间隙更紧
className="px-2 sm:px-4 py-2 sm:py-3" // 移动端内边距更小

示例 3：响应式布局

className="flex flex-col sm:flex-row"  // 移动端堆叠，桌面端行排列

示例 4：响应式可见性

<span className="hidden sm:inline">总保证金</span>  // 移动端隐藏文本，桌面端显示

参见： src/components/PortfolioSection.tsx 以获取贯穿整个应用程序的响应式模式的全面示例。

澄清性问题框架

何时提问

在执行前提出澄清性问题，当：

需求模糊不清
存在多种有效方法
决策影响架构或用户体验
用户的请求可能有多种解释方式
你需要关于业务逻辑或领域知识的上下文

问题格式模板

对所有澄清性问题使用此结构：

## 澄清性问题：[主题]

[关于为何需要提问的简要背景]

**选项 A：[方法名称]** ✅（推荐）
- [关于方法的细节]
- [关键特征]
- **优点：**[好处]
- **缺点：**[权衡]
- **专家为何偏好此选项：**[来自领域专家视角的技术推理]

**选项 B：[替代方法]**
- [关于方法的细节]
- [关键特征]
- **优点：**[好处]
- **缺点：**[权衡]
- **权衡：**[为何这不是首选]

**选项 C：[另一个替代方案]**（如果适用）
- [关于方法的细节]
- [关键特征]
- **优点：**[好处]
- **缺点：**[权衡]
- **权衡：**[为何这不是首选]

关键要求

标记最佳选项 - 使用 ✅ 表示专家推荐的选项
解释推理 - 必须包含“专家为何偏好此选项”部分
无偏见的选项 - 公平地呈现所有选项，让标记表明偏好
完整上下文 - 用户无需额外研究即可理解权衡

真实示例：交易日计算

来自今天关于如何计算交易日的对话：

## 澄清性问题 2：带日期筛选器的交易日计算

当用户设置自定义日期范围（开始日期/结束日期）时，交易日应代表：

**选项 A：所选日期范围内的日历天数** ✅（推荐）
- 示例：1月1日至1月31日 = 31天
- **优点：** 简单，符合用户对“范围内天数”的心理模型
- **缺点：** 不考虑非交易日
- **专家为何偏好此选项：** 对于投资组合分析，日历日提供基于时间的准确绩效指标，并符合金融行业年化回报的标准。

**选项 B：日期范围内实际有交易的天数（发生交易的日子）**
- 示例：1月1日至1月31日 = 仅计算发生交易的日子（例如，18天）
- **优点：** 反映实际市场活动
- **缺点：** 可能产生误导——策略设计上可能并非每日交易
- **权衡：** 更适合衡量交易频率，而非基于时间的绩效

结果： 用户选择了选项 B，展示了清晰的选项如何促成明智的决策。

决策标准

何时保留 vs 改进

使用此决策树：

代码是否损坏或不正确？
├─ 是 → 修复它（附解释）
└─ 否 → 是否存在显著更好的选项？
    ├─ 是 → 它是否满足所有例外标准？
    │   ├─ 是 → 提议改进（获得批准）
    │   └─ 否 → 保留现有代码
    └─ 否 → 保留现有代码

风险评估清单

在提议对现有代码进行任何更改之前，请验证：

[ ] 更改仅限于特定文件/函数
[ ] 对其他功能没有连锁反应
[ ] TypeScript 编译成功
[ ] 接口没有破坏性更改
[ ] 现有测试仍然通过（如果存在测试）
[ ] 可以通过单个 git revert 撤销

复杂性评估

避免不必要的复杂性：

❌ 在现有库足够时添加新库
❌ 在现有模式有效时引入新模式
❌ 过度设计简单功能
❌ 过早优化
✅ 使用现有工具和组件
✅ 遵循既定模式
✅ 简单、可读的解决方案

与其他技能的集成

此技能与其他 Portfolio Buddy 2 技能协同工作：

与 planning-framework 一起使用 - 应用马斯克的 5 步算法和 ICE 评分进行功能规划
参考 coding-standards - 在实施期间遵循 React 19 和 TypeScript 标准
检查 architecture-reference - 在添加代码前了解组件层次结构和现有模式
咨询 migration-tracker - 在开始前验证功能对等性并检查已知问题
加载 portfolio-context - 获取技术栈和架构约束的上下文

工作流程：

加载 planning-guidelines（此技能）→ 理解原则
加载 planning-framework → 规划功能方法
检查 architecture-reference → 找到代码放置位置
应用 coding-standards → 正确编写代码
更新 migration-tracker → 记录添加的内容

Portfolio Buddy 2 真实示例

示例 1：无风险利率默认值（代码保留）

任务： 将无风险利率默认值设为 4%

方法： 纯粹保留

找到现有代码：useState<number>(0)
仅更改默认值：useState<number>(4)
保留其他所有内容：输入字段、验证、在 Sortino 比率中的使用
结果： 更改了一行，零风险

示例 2：交易日更新（代码保留）

任务： 使交易日在日期范围更改时重新计算

方法： 扩展现有计算

保留现有的 tradingPeriodDays 变量和显示
添加新逻辑以从筛选后的交易中计算唯一日期
保留所有下游使用（年化增长率等）
结果： 扩展，而非替换

示例 3：总保证金按钮（无缝集成）

任务： 为起始资金添加“设为总保证金”按钮

方法： 移动/桌面端优化的集成

在现有起始资金输入框旁添加按钮
使用现有的 Portfolio Buddy 2 响应式模式：
- className="flex items-center gap-1 sm:gap-2"（响应式间距）
- <span className="hidden sm:inline">总保证金</span>（移动端隐藏文本）
- className="h-3 w-3 sm:h-3.5 sm:w-3.5"（移动端图标更小）
- touch-manipulation 类以获得更好的移动端交互
匹配现有的蓝色主题和样式
仅当 portfolioData 存在时显示（条件渲染）
结果： 感觉是原生的，在两个视口上都能工作

示例 4：年化增长率修复（例外情况）

任务： 最初只是修复交易日计算

发现： 发现年化增长率计算在数学上是错误的

应用例外：

风险极低： 孤立计算，增加了 9 行，逻辑清晰
收益巨大： 修复了夸大的回报（约高 2.4 倍），对财务准确性至关重要
不增加复杂性： 逻辑更简单（日历日 vs 交易日），更易维护

方法：

清晰地解释了问题
展示了错误与正确的公式及示例
论证了例外标准已满足
获得了用户批准
实施了修复

结果： 由于标准客观且清晰满足，用户立即批准。

总结

始终：

默认保留现有代码
为移动端和桌面端优化
提出带有 ✅ 标记推荐的澄清性问题
与现有模式无缝集成

仅当满足所有标准时：

提议改进（低风险 + 巨大收益 + 不增加复杂性）
在实施前获得用户批准

绝不：

没有正当理由就重构正常工作的代码
不必要地增加复杂性
在可以提问时猜测需求
忽视移动端或桌面端体验

此技能确保 Portfolio Buddy 2 在所有设备上保持可维护性、一致性和用户友好性，同时保留正常工作代码的稳定性。