Excessive use of type assertions (as) - Abandoning type safety
Design Anti-patterns
"Make it work for now" thinking - Accumulation of technical debt
Patchwork implementation - Unplanned additions to existing code
Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
Symptomatic fixes - Surface-level fixes that don't solve root causes
Unplanned large-scale changes - Lack of incremental approach
Basic Principles
Aggressive Refactoring - Prevent technical debt and maintain health
No Unused "Just in Case" Code - Violates YAGNI principle (Kent Beck)
Minimum Surface for Required Coverage - When introducing maintenance-surface-bearing elements (persistent state, public-contract elements or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments (reusable, future-ready, convenient for implementation) serve as tiebreakers only. Distinct from YAGNI: YAGNI is a time-axis check (refuse work for future-only needs); this principle constrains surface area at a fixed coverage point.
Comment Writing Rules
Code first: Names, types, and structure are the primary medium; add a comment only when it carries what the code cannot express. When in doubt, improve the name instead of commenting
Comment the "why", not the "what": Explain reasoning, trade-offs, constraints/edge cases, or public API contracts
No Historical Information: Do not record development history
Timeless: Write only content that remains valid whenever read
Conciseness: Keep explanations to necessary minimum
Error Handling Fundamentals
Fail-Fast Principle
Fail quickly on errors to prevent processing continuation in invalid states. Error suppression is prohibited.
For detailed implementation methods (Result type, custom error classes, layered error handling, etc.), refer to language and framework-specific rules.
Rule of Three - Criteria for Code Duplication
How to handle duplicate code based on Martin Fowler's "Refactoring":
Duplication Count
Action
Reason
1st time
Inline implementation
Cannot predict future changes
2nd time
Consider future consolidation
Pattern beginning to emerge
3rd time
Implement commonalization
Pattern established
Criteria for Commonalization
Cases for Commonalization
Business logic duplication
Complex processing algorithms
Areas likely requiring bulk changes
Validation rules
Cases to Avoid Commonalization
Accidental matches (coincidentally same code)
Possibility of evolving in different directions
Significant readability decrease from commonalization
Simple helpers in test code
Reference Representativeness
Failure mode: Adopting patterns or dependency versions from the nearest 2-3 files without verifying repository-wide usage leads to outdated patterns, version mismatches, and architecture inconsistency.
Verifying References Before Adoption
When adopting patterns, APIs, or dependencies from existing code:
IF referencing only 2-3 nearby files → THEN Grep the pattern across the repository; adopt only when ≥3 files across different directories use the same pattern
IF Grep returns 1-2 files outside the reference → THEN investigate whether those files are the canonical implementation or legacy outliers before adopting
IF Grep returns 0 files outside the reference → THEN treat the pattern as local convention; adopt only with explicit justification (e.g., consistency with surrounding code, avoiding breaking changes)
IF multiple approaches coexist in the repository → THEN identify the majority pattern (highest file count) and adopt it; state the reason when choosing a minority pattern
IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage distribution for the same dependency; if the appropriate version cannot be determined from repository state alone, escalate
IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)
Principle
Nearby code is a starting point for investigation. Verify repository-wide usage (≥3 files across different directories) before adopting a pattern as representative.
Common Failure Patterns and Avoidance Methods
Pattern 1: Error Fix Chain
Symptom: Fixing one error causes new errors
Cause: Surface-level fixes without understanding root cause
Avoidance: Identify root cause with 5 Whys before fixing
Pattern 2: Abandoning Type Safety
Symptom: Excessive use of any type or as
Cause: Impulse to avoid type errors
Avoidance: Handle safely with unknown type and type guards
Pattern 3: Implementation Without Sufficient Testing
Symptom: Many bugs after implementation
Cause: Ignoring Red-Green-Refactor process
Avoidance: Always start with failing tests
Pattern 4: Ignoring Technical Uncertainty
Symptom: Frequent unexpected errors when introducing new technology
Cause: Assuming "it should work according to official documentation" without prior investigation
Avoidance:
Record certainty evaluation at the beginning of task files
For low certainty cases, create minimal verification code first
Symptom: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns
Cause: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness
Avoidance Methods:
Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
Similar functionality found -> Use that implementation (do not create new implementation)
Similar functionality is technical debt -> Create ADR improvement proposal before implementation
No similar functionality exists -> Implement new functionality following existing design philosophy
Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
Reference representativeness check: See "Reference Representativeness" section above for IF-THEN thresholds
Debugging Techniques
1. Error Analysis Procedure
Read error message (first line) accurately
Focus on first and last of stack trace
Identify first line where your code appears
2. 5 Whys - Root Cause Analysis
Symptom: Build error
Why1: Type definitions don't match -> Why2: Interface was updated
Why3: Dependency change -> Why4: Package update impact
Why5: Major version upgrade with breaking changes
Root cause: Inappropriate version specification
3. Minimal Reproduction Code
To isolate problems, attempt reproduction with minimal code:
Remove unrelated parts
Replace external dependencies with mocks
Create minimal configuration that reproduces problem
Type Safety Fundamentals
Type Safety Principle: Use unknown type with type guards. any type disables type checking and causes runtime errors.
any Type Alternatives (Priority Order)
unknown Type + Type Guards: Use for validating external input
Generics: When type flexibility is needed
Union Types/Intersection Types: Combinations of multiple types
Type Assertions (Last Resort): Only when type is certain
Type Guard Implementation Pattern
function isUser(value: unknown): value is User {
return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
}
Type Complexity Management
Field Count: Up to 20 (split by responsibility if exceeded, external API types are exceptions)
Optional Ratio: Up to 30% (separate required/optional if exceeded)
Nesting Depth: Up to 3 levels (flatten if exceeded)
Type Assertions: Review design if used 3+ times
External API Types: Relax constraints and define according to reality (convert appropriately internally)
Refactoring Techniques
Basic Policy
Small Steps: Maintain always-working state through gradual improvements
Safe Changes: Minimize the scope of changes at once
Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding
Implementation Procedure: Understand Current State -> Gradual Changes -> Behavior Verification -> Final Validation
Priority: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement
Emergency production incident response (post-incident tests mandatory)
Test Design Principles
Test Case Structure
Tests consist of three stages: "Arrange," "Act," "Assert"
Clear naming that shows purpose of each test
One test case verifies only one behavior
Test Data Management
Manage test data in dedicated directories
Define test-specific environment variable values
Always mock sensitive information
Keep test data minimal, using only data directly related to test case verification purposes
Mock and Stub Usage Policy
Recommended: Mock external dependencies in unit tests
Merit: Ensures test independence and reproducibility
Practice: Mock DB, API, file system, and other external dependencies
Avoid: Actual external connections in unit tests
Reason: Slows test speed and causes environment-dependent problems
Test Failure Response Decision Criteria
Fix tests: Wrong expected values, references to non-existent features, dependence on implementation details, implementation only for tests
Fix implementation: Valid specifications, business logic, important edge cases
When in doubt: Confirm with user
Test Granularity Principles
Core Principle: Observable Behavior Only
MUST Test: Public APIs, return values, exceptions, external calls, persisted state
MUST NOT Test: Private methods, internal state, algorithm implementation details
Security Principles
Secure Defaults
Store credentials and secrets through environment variables or dedicated secret managers
Use parameterized queries (prepared statements) for all database access
Use established cryptographic libraries provided by the language or framework
Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
Encrypt sensitive data at rest and in transit using standard protocols
Input and Output Boundaries
Validate all external input at system entry points for expected format, type, and length
Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
Return only information necessary for the caller in error responses; log detailed diagnostics server-side
Access Control
Apply authentication to all entry points that handle user data or trigger state changes
Verify authorization for each resource access, not only at the entry point
Grant only the permissions required for the operation (files, database connections, API scopes)
Knowledge Cutoff Supplement (2026-03)
OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)
Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets
OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice
For detailed detection patterns, see references/security-checks.md
