메뉴
Maintainability assessment criteria for code review. Apply when evaluating code for readability, change tolerance, hidden assumptions, and debuggability.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | maintainability |
| description | Maintainability assessment criteria for code review. Apply when evaluating code for readability, change tolerance, hidden assumptions, and debuggability. |
| user-invocable | false |
Evaluate whether code will be easy to understand, modify, extend, and debug over time.
| Factor | Key Question | Severity |
|---|---|---|
| Readability | Understandable in 6 months? | Critical if high cognitive load |
| Change tolerance | Changes localized? | Improvement |
| Extensibility | Add without modifying? | Improvement |
| Hidden assumptions | Constraints explicit? | Critical if causes bugs |
| Debuggability | Failures traceable? | Critical if silent |
| Intent documentation | "Why" captured? | Improvement |
| Anti-Pattern | Problem | Instead |
|---|---|---|
| Clever one-liners | Requires mental parsing | Named intermediate steps |
| Scattered logic | Changes touch many files | Centralize related behavior |
| Hardcoded values | Configuration changes require code changes | Use config objects |
| Growing if/elif chains | Every new type modifies existing code | Registry or protocol pattern |
Bare except: | Swallows all errors including KeyboardInterrupt | Catch specific exceptions |
| Silent failures | No trace when things go wrong | Log errors with context |
| Comments saying "what" | Restates code | Explain "why" |
# HIGH COGNITIVE LOAD: Too much at once
def process(data):
return {k: sum(x['value'] for x in v if x.get('active', True))
for k, v in groupby(sorted(filter(lambda x: x['status'] != 'deleted',
data), key=lambda x: x['category']), key=lambda x: x['category'])}
# READABLE: Named intermediate steps
def process(data):
active_items = [x for x in data if x['status'] != 'deleted']
sorted_items = sorted(active_items, key=lambda x: x['category'])
result = {}
for category, items in groupby(sorted_items, key=lambda x: x['category']):
result[category] = sum(x['value'] for x in items if x.get('active', True))
return result
# BRITTLE: User display logic scattered
# views.py
def user_profile(user):
return f"{user.first_name} {user.last_name}"
# emails.py
def format_recipient(user):
return f"{user.first_name} {user.last_name} <{user.email}>"
# Adding middle name requires 2+ file changes
# RESILIENT: Centralized
class User:
@property
def display_name(self) -> str:
return f"{self.first_name} {self.last_name}"
@property
def email_display(self) -> str:
return f"{self.display_name} <{self.email}>"
# CLOSED: Adding new type requires modifying existing code
def process_payment(payment):
if payment.type == "credit_card":
process_credit_card(payment)
elif payment.type == "paypal":
process_paypal(payment)
elif payment.type == "crypto": # had to add this
process_crypto(payment)
# OPEN: New types don't touch existing code
class PaymentProcessor(Protocol):
def process(self, payment: Payment) -> Result: ...
PROCESSORS: dict[str, PaymentProcessor] = {
"credit_card": CreditCardProcessor(),
"paypal": PayPalProcessor(),
}
def process_payment(payment):
return PROCESSORS[payment.type].process(payment)
# HIDDEN: items is never empty
def get_average(items):
return sum(items) / len(items) # ZeroDivisionError
# EXPLICIT: Documented and enforced
def get_average(items: list[float]) -> float:
"""Calculate average. Raises ValueError if items is empty."""
if not items:
raise ValueError("Cannot calculate average of empty list")
return sum(items) / len(items)
# BAD: Silent failure
def update_user(user_id, data):
user = get_user(user_id)
if user:
user.update(data)
# if user doesn't exist... nothing happens
# BAD: Exception swallowing
try:
result = complex_operation()
except Exception:
pass
# GOOD: Specific error with context
def update_user(user_id, data):
user = get_user(user_id)
if user is None:
raise UserNotFoundError(f"No user with id {user_id}")
user.update(data)
# GOOD: Logged with structured context
def process_batch(items):
for item in items:
try:
process(item)
except Exception as e:
logger.error(f"Failed to process item {item.id}: {e}",
extra={"item_id": item.id, "item_type": item.type})
# USELESS: Restates the code
x = x + 1 # increment x
# USEFUL: Explains why
x = x + 1 # account for 0-indexing in the API response
# WITHOUT CONTEXT: What is this magic?
if (n & (n - 1)) == 0 and n != 0:
...
# WITH CONTEXT: Clear purpose
# Check if n is a power of 2 (only one bit set)
if (n & (n - 1)) == 0 and n != 0:
...
Answer these for any significant code change:
If any answer is "no", the code likely has maintainability issues worth flagging.
When flagging maintainability issues in reviews, reference this skill:
**Convention**: See `maintainability` skill: Debuggability
Google-style docstring conventions for Python code. Apply when writing or reviewing functions, classes, or modules that need documentation.
Python naming conventions for this codebase. Apply when writing or reviewing Python code including functions, classes, variables, and constants.
Python type hint conventions for this codebase. Apply when writing or reviewing Python code that needs type annotations on functions, classes, or variables.
Essential Pythonic idioms and conventions. Apply when writing or reviewing Python code to ensure idiomatic patterns like comprehensions, built-in functions, context managers, and unpacking.
Python code organization conventions for this codebase. Apply when structuring modules, organizing imports, designing file layouts, or moving functions/classes within or between files. Use PROACTIVELY when users request to check code organization, move code, or clean up and reorganize a module.
Refactoring complex functions into smaller, pure helper functions. Apply when function complexity is exceeded or when extracting helper functions during refactoring. If tasked with fixing ruff lint errors related to complexity, ALWAYS trigger this skill.