菜单
USE WHEN: 读/写/重构 Python CLI 脚本或工具(.claude/skills/*/scripts/ 下任意 .py)、规划模块拆分、code review Python 改动。OUTPUT: 设计建议 + 复杂度评估,基于 Ousterhout《A Philosophy of Software Design》。DO NOT USE: 业务代码逻辑设计 / pytest 用法咨询 / 性能调优 / Web 框架问题。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
流程编排引擎。推进 task.json.flow 步骤（init/check/complete/reset）并维护任务级事件流 task.json.events（emit/check/recent）。触发关键词：flow advance、推进流程、当前步骤、初始化流程、emit event、查事件、task.json.events、flow-engine。
TAPD 统一入口 skill。工单拉取、共识管理、子任务回填、事件驱动同步。触发关键词：tapd、初始化、ticket sync、共识、Wiki 评审、子任务、工时回填、QA 通过、QA 打回、TAPD 事件、契约推送、同步工单、拉工单。
产出结构化 handoff 工件，让新 session 无痕接续当前任务。ctx-guard 阻断或主动切换 session 时使用。触发关键词：context reset、上下文重置、新开 session、切换 session、handoff。
运行架构适应度函数检查代码结构、契约、依赖方向。在代码修改前后使用，确保不引入架构违规。触发关键词：fitness、架构检查、适应度、lint、代码质量检查。
工作流熵管理。清理 stale TAPD cache、孤立 _index 条目、过期 task report。每日定时或手动触发。触发关键词：gc、垃圾回收、清理、cleanup、定时清理。
Git 操作统一入口。分支生命周期（create/merge/cleanup）、worktree（create/remove）、提交推送（commit-push）。按 docs/git-brance-spec.md + Conventional Commits 中文规范执行。触发关键词：创建分支、合并到 dev、合并到 uat、删除分支、清理分支、git push、commit、推送代码、worktree、提交代码。
| name | python-design |
| description | USE WHEN: 读/写/重构 Python CLI 脚本或工具(.claude/skills/*/scripts/ 下任意 .py)、规划模块拆分、code review Python 改动。OUTPUT: 设计建议 + 复杂度评估,基于 Ousterhout《A Philosophy of Software Design》。DO NOT USE: 业务代码逻辑设计 / pytest 用法咨询 / 性能调优 / Web 框架问题。 |
基于 A Philosophy of Software Design (Ousterhout) 的设计原则,针对 CLI 脚本与工具场景。
核心挑战是管理复杂度,不是增加功能。 复杂度有三个症状:
复杂度是增量累积的,通过数百个小决策而不是一次灾难性错误。所以:关注小事(sweat the small stuff)。
sys.path.insert(0, ...) 黑魔法 —— 修包结构(用 python -m 或 __init__.py)common/* 函数不加 _ 前缀(被复用就是 public API,加 _ 会让 import 看起来违规)subprocess 输出别 .strip(),会破坏语义空格(如 git submodule status 行首前缀字符 /-/+)—— 用 .rstrip("\n\r")| # | 原则 | 一句话摘要 | 详读 |
|---|---|---|---|
| 1 | Deep Modules | 模块价值 = 封装功能 / 暴露接口的比率 | 01-deep-modules.md |
| 2 | Type-First Development | 类型先定义契约,实现满足类型 | 02-type-first.md |
| 3 | Information Hiding | 同一知识不该出现在多个模块 | 03-information-hiding.md |
| 4 | Pull Complexity Down | 复杂度由模块内部吸收,不推给调用方 | 04-pull-complexity.md |
| 5 | Define Errors Out | 用 postcondition 设计 API,让错误不再是错误 | 04-pull-complexity.md |
| 6 | KISS + Rule of Three | 选最简方案;三次重复才抽象 | 05-kiss-and-srp.md |
| 7 | Single Responsibility | 每个模块一个改变理由;按 information 拆分不按 execution | 05-kiss-and-srp.md |
| 8 | Consistent Shared Infra | 多脚本需要的能力放 common/,一次实现 | 06-shared-infra.md |
| 9 | Structured CLI Parsing | 解析 shell 输出尊重语义空格 | 06-shared-infra.md |
| 你在做… | 读这个 |
|---|---|
| Code review / 自审 | red-flags.md — 12 类反模式速查 |
| 写代码前 / review 中 | checklist.md — 6 项设计自检清单 |
每次改动花 10-20% 时间改善周边设计 —— 不是完美主义,是复利。可工作的代码必要但不充分,软件开发的增量应该是抽象,不只是 feature。