python-code-implementation-workflow
A workflow for building and refactoring Python code using Test-Driven Development and vectorized data processing patterns.
Install
mkdir -p .claude/skills/python-code-implementation-workflow && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/15069" && unzip -o skill.zip -d .claude/skills/python-code-implementation-workflow && rm skill.zipInstalls to .claude/skills/python-code-implementation-workflow
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Implement and refactor Python code with TDD, API signature discipline, and maintainable design. Use for feature development, bug fixes, test-first workflows, and quality-focused refactoring.Key capabilities
- →Deliver working Python code guided by tests
- →Keep APIs clear and stable
- →Preserve maintainability through small, focused functions
- →Implement new features using TDD
- →Fix bugs with behavior preservation
- →Add tests for existing logic
How it works
The skill guides Python code implementation through a Test-Driven Development cycle, enforcing API signature rules, single responsibility for functions, and prioritizing vectorization for performance-sensitive tasks.
Inputs & outputs
When to use python-code-implementation-workflow
- →Implement new Python features using a test-first approach
- →Refactor slow Python loops into vectorized NumPy or pandas operations
- →Fix bugs while maintaining existing API contracts
- →Ensure modular design with single-responsibility functions
About this skill
Python Code Implementation Workflow
Reusable workflow for implementing Python code with predictable quality and test coverage.
Outcome
- Deliver working code guided by tests.
- Keep APIs clear and stable.
- Preserve maintainability through small, focused functions.
Use When
- Implementing new features.
- Fixing bugs.
- Refactoring with behavior preservation.
- Adding tests for existing logic.
Constraints
- Follow Test-Driven Development (TDD) by default.
- Keep function design aligned with single responsibility.
- Use at most 2 mandatory positional arguments per function.
- Make all remaining parameters keyword-only.
- Preserve backward compatibility for public APIs unless explicitly approved.
- Keep all module and package imports at module scope, never inside functions or methods. Follow PEP 8: place imports after the module docstring and any
__future__imports, before module globals and constants; group standard-library, third-party, and local imports separately with blank lines, and use separate lines for separate module imports. - Keep module and package dependencies acyclic: if package A imports any module from package B, package B must not import any module from package A, directly or transitively. Apply the same rule between modules within a package. Do not hide architectural cycles with local imports, dynamic imports, or
TYPE_CHECKINGguards; restructure ownership and dependency direction instead. - Avoid hidden coupling: depend on explicit public contracts, not another module's private state or implementation details. An internal change to one class should not require unrelated consumers and their tests to change unless its public contract changes.
- Keep each Python script or module at or below 1,500 lines. Before creating or extending a file beyond this limit, or adding code to an already oversized file, stop and present module-splitting or refactoring options and their trade-offs to the user. Discuss the options and obtain approval for the approach before proceeding.
Performance Defaults (Vectorization-First)
For performance-sensitive data-processing and result-collection code:
- Prefer NumPy/pandas vectorization over Python row-by-row loops when behavior can be preserved.
- Prefer one-pass extraction into arrays (for example with
np.fromiter) and reuse arrays for totals, filtering, and exports. - Prefer constructing DataFrames once from column arrays instead of repeated list appends in loops.
- Prefer
reshape/repeat/tilepatterns for cartesian-index outputs (for example(hour, tech)and(line, hour)). - Preserve exact output schema and column ordering when refactoring to vectorized paths.
- Use Python loops only when vectorization would materially reduce clarity or change semantics.
Procedure
1. Define Behavior First
- Identify acceptance criteria and edge cases.
- Define expected inputs, outputs, and failure modes.
- Determine whether API changes are required.
2. Apply TDD Cycle (Mandatory)
- Write a failing test first.
- Implement the smallest change needed to pass.
- Refactor while keeping tests green.
- Repeat for each behavior slice.
3. Enforce API Signature Rules
- Keep maximum 2 mandatory positional arguments.
- Use
*to force keyword-only optional arguments. - Place the primary object first.
- Use safe defaults for optional parameters.
- Do not remove or reorder existing public parameters.
Signature Pattern
def function_name(
primary_object,
secondary_input,
*,
option1=default1,
option2=default2,
verbose=False,
):
"""Implement behavior for a single responsibility."""
4. Keep Single Responsibility
- Ensure each function has one clear purpose.
- Extract helpers when a function starts handling multiple concerns.
- Keep orchestration separate from transformation/validation logic.
- Before adding imports, check dependency direction for direct cycles (
A -> B -> A) and indirect cycles (A -> B -> C -> A), including imports through package re-exports. - Break cycles by moving shared contracts or data into a lower-level module that imports neither consumer, injecting dependencies through those contracts, or moving cross-domain queries into an orchestration layer.
- Investigate hidden coupling when an implementation-only change breaks unrelated tests. Remove assumptions about private fields, internal representations, or undocumented behavior rather than patching every consumer.
5. Write and Expand Tests
- Add unit tests for normal behavior.
- Add edge-case tests (empty, boundary, null-like inputs).
- Add error-path tests (exceptions and messages).
- Parameterize repeated input/output checks.
6. Final Quality Pass
- Run the relevant test suite.
- Confirm no behavior regressions in touched areas.
- Verify API compatibility and call-site impact.
- Add or update NumPy-style docstrings for changed public functions.
- Confirm imports are at module scope and follow PEP 8 placement and grouping.
- Check Python file lengths; confirm any work exceeding the 1,500-line limit followed the required user discussion and approval.
- Confirm module and package dependencies remain acyclic and consumers use explicit public contracts rather than implementation details.
Patterns and Anti-patterns
API Signature Patterns
# GOOD
def run_operation(
model,
data,
*,
solver="highs",
time_limit=3600,
verbose=False,
):
return solve(model, data, solver=solver, time_limit=time_limit, verbose=verbose)
# BAD: too many positional arguments
def run_operation(model, data, solver, time_limit, gap_tolerance, verbose):
return solve(model, data, solver=solver, time_limit=time_limit, verbose=verbose)
Single Responsibility Patterns
# GOOD: validation and transformation are separated
def validate_input(data):
if not data:
raise ValueError("data cannot be empty")
def transform_data(data, *, scale=1.0):
return [value * scale for value in data]
# BAD: multiple responsibilities mixed together
def process_data(data, scale=1.0, save_path=None):
if not data:
raise ValueError("data cannot be empty")
transformed = [value * scale for value in data]
if save_path:
with open(save_path, "w", encoding="utf-8") as file_obj:
file_obj.write(str(transformed))
return transformed
Vectorization Patterns
# GOOD: one-pass extraction + vectorized DataFrame build
values = np.fromiter((get_value(i) for i in idx), dtype=float, count=len(idx))
df = pd.DataFrame({"idx": np.asarray(idx), "value": values})
# BAD: row-by-row append in hot paths
rows = []
for i in idx:
rows.append({"idx": i, "value": get_value(i)})
df = pd.DataFrame(rows)
Dependency Direction and Coupling Patterns
Anti-pattern: furniture imports workers to answer table.isdoneby(), while
workers imports furniture to answer carpenter.whatdo(). This creates a cycle,
even when the imports are spread across different modules in each package.
# BAD: furn.py
from .workers import Carpenter
class Table:
def isdoneby(self):
return Carpenter.lookup(self._maker_id)
# BAD: workers.py
from .furn import Chair, Table
class Carpenter:
def whatdo(self):
return Table.find_by_maker(self) + Chair.find_by_maker(self)
Do not move these imports inside the methods to make the cycle load successfully. Instead, separate shared relationship data from concrete classes. For example, both modules can depend on an immutable record, and an orchestration layer can provide the same records to furniture and workers. Neither domain imports the other; the shared module imports neither domain.
# GOOD: contracts.py
from dataclasses import dataclass
@dataclass(frozen=True)
class WorkRecord:
item_name: str
maker_id: str
# GOOD: furn.py (Chair can use the same pattern)
from dataclasses import dataclass
from .contracts import WorkRecord
@dataclass(frozen=True)
class Table:
work: WorkRecord
def isdoneby(self) -> str:
return self.work.maker_id
# GOOD: workers.py
from dataclasses import dataclass
from .contracts import WorkRecord
@dataclass(frozen=True)
class Carpenter:
work: tuple[WorkRecord, ...]
def whatdo(self) -> tuple[str, ...]:
return tuple(record.item_name for record in self.work)
These are alternative design sketches, not a drop-in refactor preserving the bad example's object-returning API. Preserve existing public behavior when applying this pattern to production code.
Hidden-coupling anti-patterns include reading table._parts, assuming the order
of its internal collections, or copying its completion logic into Carpenter.
Prefer a documented public query or a small shared contract instead. If changing
Table's internal representation breaks many unrelated Carpenter tests, repair
the dependency boundary rather than encoding more implementation assumptions.
TDD Patterns
# GOOD FLOW
# 1) Write failing test
# 2) Implement minimal code to pass
# 3) Refactor with tests still passing
# ANTI-PATTERN
# Write large implementation first, then add tests afterward.
Completion Criteria
- TDD loop was followed for implemented behavior.
- Functions keep single responsibility.
- All new/changed signatures follow max-2-positional and keyword-only rules.
- Tests cover normal, edge, and error behavior for modified logic.
- Public API compatibility is preserved or explicitly documented.
- Imports are at module scope and follow PEP 8.
- Module and package dependencies are acyclic, including transitive dependencies and package re-exports.
- Consumers rely on explicit public contracts; internal implementation changes do not require unrelated consumer changes.
- Python files stay within 1,500 lines, or the user has discussed the options and approved the approach before work exceeding the limit proceeds.
Content truncated.
When not to use it
- →When Test-Driven Development is not desired
- →When API signature rules are not applicable
Limitations
- →It requires following Test-Driven Development (TDD) by default.
- →Functions must use at most 2 mandatory positional arguments.
- →Public API backward compatibility must be preserved unless explicitly approved.
How it compares
This skill enforces a disciplined TDD workflow with strict API signature rules and a vectorization-first approach for Python, providing a structured method for quality-focused implementation and refactoring that differs from ad-hoc coding.
Compared to similar skills
python-code-implementation-workflow side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| python-code-implementation-workflow (this skill) | 0 | 6mo | No flags | Intermediate |
| agent-implementer-sparc-coder | 1 | 9mo | Review | Intermediate |
| clojure-write | 16 | 6mo | No flags | Intermediate |
| add-uint-support | 18 | 1y | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
agent-implementer-sparc-coder
ruvnet
Agent skill for implementer-sparc-coder - invoke with $agent-implementer-sparc-coder
clojure-write
metabase
Guide Clojure and ClojureScript development using REPL-driven workflow, coding conventions, and best practices. Use when writing, developing, or refactoring Clojure/ClojureScript code.
add-uint-support
pytorch
Add unsigned integer (uint) type support to PyTorch operators by updating AT_DISPATCH macros. Use when adding support for uint16, uint32, uint64 types to operators, kernels, or when user mentions enabling unsigned types, barebones unsigned types, or uint support.
python-patterns
affaan-m
Pythonic 惯用法、PEP 8 标准、类型提示以及构建健壮、高效、可维护的 Python 应用程序的最佳实践。
modern-python
trailofbits
Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
adk-engineer
jeremylongshore
Execute software engineer specializing in creating production-ready ADK agents with best practices, code structure, testing, and deployment automation. Use when asked to "build ADK agent", "create agent code", or "engineer ADK application". Trigger with relevant phrases based on skill purpose.