Community程式設計與開發github.com

python-reduce-complexity

衡量並降低 Python 程式碼的複雜度(以強制式詞彙 Token 數量計算),提出簡化方案並驗證功能等價性,最後重新測量以確認 Token 數確實下降。

python-reduce-complexity 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor、Codex 等)設計的技能,用於衡量並降低 Python 程式碼的複雜度。其核心機制是透過內建指令稿 `imperative_tokens.py` 計算強制式詞彙 Token 的數量(僅計算實際執行邏輯的語法,排除宣告、型態註記、匯入等),並以此作為簡化的代理指標。 此工具不僅能回報複雜度數據,還能自動提出具體的簡化方案(例如用標準函式庫取代手寫邏輯、消除重複程式碼、重構分支結構),並對每項變更進行功能等價性驗證,包括測試套件比對或直接輸出比較。若變更會改變行為(例如 `x or default` 取代 `x if x is not None else default`,會影響假值),需提供論證(如該輸入情境不可能發生、無人觀察此差異)。 它支援 `.py` 檔案與 Jupyter Notebook (`.ipynb`),並會自動處理 Notebook 中的魔術指令與 Shell 指令。適用於開發者或 AI 代理需要優化程式碼可讀性、降低維護成本、審核程式碼複雜度變動的場景。最終產出一份報告,列出每個檔案的 Token 增減、已驗證的等價變更、需使用者確認的非等價變更,以及被否決的提案與原因。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jachymb/skills/tree/main/python-reduce-complexity

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

降低 Python 複雜度

檔案:$ARGUMENTS

程式碼複雜度宜保持低水平。複雜度以 Python 詞彙 Token 中屬於強制式程式碼(即執行某種動作的語法)的數量來衡量。宣告是用來組織程式碼的,不會增加邏輯,因此不計入。

哪些算在內

定義方式請見與此檔案同目錄的 imperative_tokens.py。

不計入:

  • def 和 class 的標頭,從第一個裝飾器到冒號(主體開頭):裝飾器、參數、預設值、基底類別、回傳型態註記。這一切只在定義時計算一次,並宣告一個介面。
  • 型態註記(x: int = 1 視為 x = 1,x: int 視為無)、type 別名。
  • 匯入、註解、文件字串、換行與縮排。
  • 呼叫中的關鍵字參數名稱:f(key=value) 與 f(value) 權重相同。在大部分情況下,建議使用關鍵字傳遞引數,因此不計成本。
  • 屬性限定:a.b.c.d 與 d 權重相同。點狀路徑只命名一個物件。若將其計入,將獎勵 from numpy import log 勝過 np.log,或為 self.x 建立本地別名,而這兩者都不會改變任何邏輯。

計入: 所有其他 Token。陳述式(if、for、while、try、with、return、raise……)、賦值、運算子、呼叫、字面值、推導式與 Lambda,以及它們的逗號、冒號和成對括號中的任一個。因此,一個呼叫比執行相同動作的運算子多 1 個 Token:a.update(b) 是 4 個 Token,a |= b 是 3 個。

對於筆記本 (.ipynb),只計算程式碼儲存格。魔術或 Shell 指令行(%config …、!pip …)視為 IPython 將其轉換成的呼叫。位於儲存格魔術(%%bash、%%html)下的儲存格計為 0。例外情況是執行主體為 Python 的儲存格魔術(IPython 的 ExecutionMagics,例如 %%time 和 %%capture):魔術部分計為一行魔術,主體則計為程式碼。非 IPython 內建魔術(例如來自擴充套件)計為 0,指令稿會印出警告:請在報告中傳遞該警告。核心非 Python 的筆記本計為 0。指令稿僅在處理 Python 筆記本時才匯入 IPython,並向它詢問哪些魔術是內建的。

Token 數量只是代理指標

Token 數量降低是簡化的證據,而非簡化本身。

  • 允許重大重構: 新增輔助函式、新增基底類別、新增檔案。此時會比較所有受影響檔案的總和(步驟 4),因此在檔案間移動邏輯會相互抵銷。
  • 需要自行提出理由: 將邏輯移到指令稿不會檢查的地方(如預設值、裝飾器引數、基底類別表達式或新的相依套件)。提案需解釋為何此變更除了降低 Token 數之外,還是好的。
  • 禁止: 將程式碼放入字串中透過 eval、exec 或類似的外部執行方式來執行。
  • 內聯只使用一次的變數 只有在不損害可讀性的情況下才可接受。為中間變數取一個好名稱有助於讀者理解意圖。
  • 不視為降低: 移除行為(邊界驗證、錯誤處理、支援的情況),以及為了減少幾個 Token 而犧牲可讀性(密集的單行、移除結尾逗號)。

專案本身的規則(CLAUDE.md、編碼規範)優先於 Token 數量。

非嚴格等價的變更

若變更為了簡化而改變行為,但能論證程式仍保持正確,則允許。提案需說明何處不同、針對哪些輸入,以及論證及其在程式碼中的證據:

  • 此不同的輸入不可能發生。 證據:建構或驗證該值的程式碼。
  • 沒有人會觀察到此差異。 證據:列出該值的每個消費端。
  • 此差異可觀察但無害: 例如取自播種隨機產生器、較慢的演算法、提前引發的錯誤。這需要使用者明確同意。任何公開回傳值、寫入輸出或測試能看到的差異也同樣需要使用者同意。

以下是一些範例,說明論證的形式。任何其他改變行為的變更都應以相同方式論證,不論是否與以下範例類似:

簡化形式取代差異點
x or defaultx if x is not None else default會將假值 x(0、""、[])也取代掉
zip(a, b)透過 range(len(a)) 對兩者索引較短的 b 會無聲截斷;strict=True 保留此檢查
a // bint(a / b)負數運算元會朝不同方向四捨五入
max(xs, key=f)sorted(xs, key=f)[-1]平手時,第一個相等項目勝出,而非最後一個
xs.sort()xs = sorted(xs)呼叫者傳入的串列被修改(就地排序)
Counter(xs)計數迴圈讀取缺失的鍵會回傳 0,而非引發例外
以 @dataclass 定義,用 row.name 讀取以 dict 記錄,用 row["name"] 讀取索引、.get、** 解包與 JSON 序列化將失效

論證必須基於程式碼,而非今日的資料:「此檔案沒有重複資料」不是有效論證,「可能唯一」也不是。移除行為(如邊界驗證)仍屬排除範圍,不能透過論證來規避。

不確定時,由使用者決定。 若證據不完整(消費端在儲存庫之外、無法讀取建構值的程式碼),或不確定某個差異是否無害,則不要自行定案。提供該變更以及差異點與未知的部分,繼續處理其他提案,並僅在使用者同意後才套用該變更。

標準函式庫形式

以下是一些常見情況的範例,說明這類取代的樣貌。這並非完整目錄:內建函式、標準函式庫與專案已安裝的相依套件提供了更多選擇,表格中未列出的取代方式也同樣有效。

標準形式取代差異點
@dataclass,搭配 field(default_factory=list)、order=True、frozen=True僅儲存參數的 __init__;手寫的 __eq__、__repr__、__lt__、__hash__原先沒有 __eq__ 的類別現在會以值比較且無法可雜湊(eq=False 保留身份比較);__eq__ 也會比較類別;明確的 None 不再成為預設值
any(p(x) for x in xs)、all(…)、next(filter(p, xs), None)帶 break 的旗標或搜尋迴圈無
defaultdict(list)if key not in groups: groups[key] = []讀取缺失的鍵會插入該鍵
@cache、@cached_property記憶字典;if self._x is None 惰性屬性在方法上使用 @cache 會保持它呼叫過的每個實例存活;此屬性需用 del 重置,而非賦值為 None
itemgetter("foo")、str.strip、operator.mul只索引、只呼叫一個方法或只套用一個運算子的 Lambdastr.strip 在非字串值上會引發例外
Path(path).read_text()with open(path) as file: 與 file.read()無
name.removeprefix(prefix)、line.partition("=")startswith 與切片;split 與長度檢查無
chain.from_iterable(xss)[x for xs in xss for x in xs]迭代器:若結果會被索引或讀取兩次,請用 list 包裝
batched(xs, n)在 range(0, len(xs), n) 上使用 xs[i:i + n]回傳元組迭代器,而非切片串列
@singledispatchisinstance 鏈最特定的註冊類別勝出,而非第一個符合的測試;分發的引數是第一個,以位置傳遞

@singledispatch 與 @dataclass 的引數會將邏輯移到標頭中,而這是指令稿不會檢查的地方。它們除了 Token 數之外的理由:產生的方法會遵循欄位清單,不會偏離;每個型別都有專屬的函式,新增型別時不會影響到現有函式。

其他形式只有在特定上下文下才有幫助,因此需要額外考量:

  • itertools.product 或 itertools.combinations 可以取代巢狀迴圈。
  • functools.reduce 可以取代沒有內建函式的摺疊操作。

步驟

  1. 基準線。 使用專案的 Python 解譯器(Python 3.12 或更新版本)對引數中的檔案執行指令稿,並保留輸出:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <file.py | notebook.ipynb> [...]
    

    立即執行測試:在變更前就失敗的測試套件無法驗證變更後的任何內容。如果使用者只要求測量,則回報結果並停止。

  2. 提案。 閱讀程式碼以理解其計算的內容,而非尋找可匹配的模式。對於每個函式、迴圈與分支,拷問是否能用更少的 Token 表達相同的結果。此技能中的串列與表格展示了簡化的樣貌。但這些並非搜尋空間:大部分可以刪除的內容都是特定於該程式碼的,沒有任何串列能預先涵蓋。僅檢查所列模式的遍歷是不完整的。

    常見的發現,大致按產出排序:

    • 死程式碼:未使用的函式、參數與無法到達的分支;
    • 相同邏輯寫了兩次(在此檔案或其他檔案中),可用共用的輔助函式或基底類別保留一份;
    • 手寫的程式碼,但標準函式庫、內建函式或已安裝的相依套件已提供;標準函式庫工具如 itertools、functools、operator、collections 或 dataclasses 可能有幫助,上述「標準函式庫形式」列出了常見情況;
    • 建構值的迴圈:推導式通常優於迴圈,偶爾 filter 或 map 內建函式比推導式更簡單;
    • 可被重載運算子取代的方法呼叫:a | b 取代 a.union(b)、a |= b 取代 a.update(b)、a @ b 取代 a.dot(b)。先檢查運算元型別:對集合使用 |= 需要集合,而 .update() 接受任何可迭代物件;
    • 可折疊為資料結構(對應表)或一般路徑的分支;
    • 僅為了被撤銷而存在的狀態與轉換;
    • 遠離程式邊界的防禦性檢查;
    • 比其輸入需求更嚴格的程式碼,其中較簡單的形式僅在不可能發生或無人觀察的輸入上有所不同(上表)。

    然後再次檢查整個程式碼,先處理最長的函式,尋找不屬於上述任何一類的內容:不同的演算法或資料結構,使簿記變得多餘;重新安排計算順序,使特殊情況消失;專案已使用的相依套件中的某個函式可以完全勝任;兩個函式僅在一個值上不同。此類提案與任何列出的提案遵循相同規則。

    若要評估一段程式碼(例如提案前後的幾行),可將其透過管線傳送給指令稿,而不指定檔案引數。它會只印出 Token 數。該程式碼片段必須能獨立解析,因此請移除縮排:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF'
    uncounted |= set(range(first, last))
    EOF
    

    每個提案應以程式碼形狀呈現,列出前後關鍵行、預期減少的 Token 數、影響的其他檔案,以及上述章節要求的任何理由或論證。在使用者同意後套用,或若使用者已要求直接進行變更,則可直接套用。

  3. 套用與驗證,一次一個提案,以便失敗時能指出原因。

    • 在首次編輯基準線中未包含的檔案之前,先測量該檔案並將其加入基準線。新檔案從 0 開始。
    • 測試必須通過且未經修改。與其檢查的程式碼一起被編輯的測試不再能檢查該程式碼;若測試必須修改(例如它呼叫了被移除的輔助函式),請說明。
    • 從未執行變更後程式碼的測試無法證明任何事。對於這些程式碼行,在相同輸入(包含邊界情況)上分別執行舊版本(git stash,或 git show HEAD:<path> 到暫存檔案)與新版本,並比較輸出。浮點數結果必須相同,否則報告需說明差異的大小。
    • 非嚴格等價的變更,必須在其論證所允許的輸入上進行比較。然後檢查論證本身:閱讀建構該值的程式碼,或搜尋每個消費端。無法成立的證據將導致提案被否決。
    • 公開行為(簽名、例外型別、輸出的順序)的變更不屬於等價變更。需要使用者明確同意。
  4. 重新測量。 對所有受影響的檔案執行指令稿:包括引數中的檔案以及變更所編輯或建立的每個其他檔案。已刪除的檔案計為 0。合計總數必須低於合計基準線,否則還原變更。步驟 3 失敗的變更也同樣還原。

  5. 報告。 分別列出每個受影響檔案及合計結果:變更前後與差異的 Token 數。然後說明驗證等價性的方式(哪些測試、哪些直接比較)、每個非嚴格等價的變更(附上差異點與論證)、每個等待使用者決定的變更,以及每個被否決的提案(附上原因)。

相關技能