impl-standards

实施标准

在实施过程中遵循这些标准，确保代码一致且易于维护。

自我进化的技能：此技能会在使用过程中不断完善。如果说明有误、参数已偏移或需要采用变通方案，请立即修复此文件，不要拖延。仅针对实际且可复现的问题进行更新。

何时使用此技能

• 在 /itp:go 第 1 阶段
• 编写新的生产代码时
• 用户提到“错误处理”“常量”“魔法数字”“进度日志”“SSoT”“依赖注入”或“配置单例”时
• 发布前验证代码质量时

快速参考

标准	规则
错误	抛出并传播；不回退、不设默认值、不重试、不静默处理
常量	将魔法数字提取为语义明确、与版本无关的动态常量
SSoT/DI	配置单例 → 默认值为 None → 解析器 → 入口点验证
依赖项	优先使用开源库而非自定义代码；无需考虑向后兼容
进度	耗时超过 1 分钟的操作：每 15-60 秒记录一次状态
日志	logs/{adr-id}-YYYYMMDD_HHMMSS.log（nohup）
元数据	可选：使用 catalog-info.yaml 进行服务发现

---

错误处理

核心规则：抛出并传播；不回退、不设默认值、不重试、不静默处理

# ✅ Correct - raise with context
def fetch_data(url: str) -> dict:
    response = requests.get(url)
    if response.status_code != 200:
        raise APIError(f"Failed to fetch {url}: {response.status_code}")
    return response.json()

# ❌ Wrong - silent catch
try:
    result = fetch_data()
except Exception:
    pass  # Error hidden

详细模式请参阅错误处理参考。

---

常量管理

核心规则：将魔法数字提取为语义明确的常量

# ✅ Correct - named constant
DEFAULT_API_TIMEOUT_SECONDS = 30
response = requests.get(url, timeout=DEFAULT_API_TIMEOUT_SECONDS)

# ❌ Wrong - magic number
response = requests.get(url, timeout=30)

模式请参阅常量管理参考。

---

进度日志

对于耗时超过 1 分钟的操作，每 15-60 秒记录一次状态：

import logging
from datetime import datetime

logger = logging.getLogger(__name__)

def long_operation(items: list) -> None:
    total = len(items)
    last_log = datetime.now()

    for i, item in enumerate(items):
        process(item)

        # Log every 30 seconds
        if (datetime.now() - last_log).seconds >= 30:
            logger.info(f"Progress: {i+1}/{total} ({100*(i+1)//total}%)")
            last_log = datetime.now()

    logger.info(f"Completed: {total} items processed")

---

日志文件约定

将日志保存到：logs/{adr-id}-YYYYMMDD_HHMMSS.log

# Running with nohup
nohup python script.py > logs/2025-12-01-my-feature-20251201_143022.log 2>&1 &

---

---

数据处理

核心规则：对于 dataframe 操作，优先使用 Polars 而非 Pandas。

场景	建议
新建数据管道	使用 Polars（快 30 倍，惰性计算）
ML 特征工程	Polars → Arrow → NumPy（零拷贝）
MLflow 日志记录	可使用 Pandas（添加例外说明注释）
修复旧代码	保留现有库

例外机制：在文件顶部添加：

# polars-exception: MLflow requires Pandas DataFrames
import pandas as pd

决策树和基准测试请参阅 ml-data-pipeline-architecture。

---

相关技能

技能	用途
adr-code-traceability	在代码中添加 ADR 引用
code-hardcode-audit	发布前检测硬编码值
ml-data-pipeline-architecture	Polars/Arrow 效率模式

---

参考文档

• 错误处理 - 抛出并传播模式
• 常量管理 - 魔法数字抽象
• SSoT / 依赖注入 - 配置单例 → 默认值为 None → 解析器链

---

故障排查

问题	原因	解决方案
无声失败	裸露的 except 代码块	捕获特定异常，记录日志或重新引发
代码中有魔法数字	缺少常量	提取为具有上下文的命名常量
错误被吞掉	except: pass 模式	继续执行前记录错误，或重新引发
运行时类型错误	缺少验证	在边界处添加输入验证
配置未加载	硬编码路径	使用带默认值的环境变量

执行后反思

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生了变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通方案？ — 如果你不得不临时变通（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时需要相同的变通方案。

仅在问题确实存在且可复现时进行更新，不要基于猜测更新。