# Ai Development Guide

> Anti-pattern detection, debugging techniques, quality check workflow, and implementation completeness assurance. Use when: fixing bugs, reviewing code quality, refactoring, making technical decisions, or performing quality assurance.

- **Type:** Skill
- **Install:** `agentstack add skill-shinpr-codex-workflows-ai-development-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shinpr](https://agentstack.voostack.com/s/shinpr)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shinpr](https://github.com/shinpr)
- **Source:** https://github.com/shinpr/codex-workflows/tree/main/.agents/skills/ai-development-guide

## Install

```sh
agentstack add skill-shinpr-codex-workflows-ai-development-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection

## Language-Specific References

For frontend-specific anti-patterns, debugging, and quality checks:
- **React/TypeScript Frontend**: [references/frontend.md](references/frontend.md)

## Technical Anti-patterns (Red Flag Patterns) [MANDATORY]

**IMMEDIATELY stop and reconsider design** when detecting the following patterns:

### Code Quality Anti-patterns
1. **Writing similar code 3 or more times** - Violates Rule of Three
2. **Multiple responsibilities mixed in a single file** - Violates Single Responsibility Principle (SRP)
3. **Defining same content in multiple files** - Violates DRY principle
4. **Making changes without checking dependencies** - Potential for unexpected impacts
5. **Disabling code with comments** - Should use version control
6. **Error suppression** - Hiding problems creates technical debt
7. **Bypassing safety mechanisms (type systems, validation, contracts)** - Circumventing correctness guarantees

### 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** - EVALUATE unknown elements with minimal verification code first
- **Symptomatic fixes** - Identify root cause with 5 Whys instead of applying surface-level patches
- **Unplanned large-scale changes** - Use incremental approach with phased implementation

**ENFORCEMENT**: Detecting ANY anti-pattern requires IMMEDIATE design review before proceeding

## Fail-Fast Fallback Design Principles

### Core Principle [MANDATORY]
Make errors explicit with full context. Prioritize primary code reliability over fallback implementations. Silent fallbacks are PROHIBITED.

### Implementation Guidelines

#### Default Approach [MANDATORY]
- **Prohibit unconditional fallbacks**: NEVER automatically return default values on errors
- **Make failures explicit**: Errors MUST be visible and traceable
- **Preserve error context**: Include original error information when re-throwing

#### When Fallbacks Are Acceptable
- **Only with explicit Design Doc approval**: Document why fallback is necessary
- **Business-critical continuity**: When partial functionality is better than none
- **Graceful degradation paths**: Clearly defined degraded service levels

#### Layer Responsibilities
- **Infrastructure Layer**: Always throw errors upward; no business logic decisions; provide detailed error context
- **Application Layer**: Make business-driven error handling decisions; implement fallbacks only when specified in requirements; log all fallback activations

### Error Masking Detection

**Review Triggers** (require design review):
- Writing 3rd error handler in the same feature
- Multiple error handling blocks in single function/method
- Nested error handling structures
- Error handlers that return default values without logging

**Before Implementing Any Fallback** [MANDATORY]:
**STEP 1**: Verify Design Doc explicitly defines this fallback
**STEP 2**: Document the business justification
**STEP 3**: Ensure error is logged with full context
**STEP 4**: Add monitoring/alerting for fallback activation

**ENFORCEMENT**: Fallbacks without Design Doc approval are PROHIBITED

### Implementation Pattern

```
AVOID: Silent fallback that hides errors
    :
        return DEFAULT_VALUE  // Error hidden, debugging impossible

PREFERRED: Explicit failure with context
    :
        log_error('Operation failed', context, error)
          // Re-throw, return Error type, return error tuple
```

## 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

## 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: Circumventing Correctness Guarantees
**Symptom**: Bypassing safety mechanisms (type systems, validation, contracts)
**Cause**: Impulse to avoid correctness errors
**Avoidance**: Use language-appropriate safety mechanisms

### 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 things work without prior investigation
**Avoidance**:
- Record certainty evaluation at the beginning of task files
- For low certainty cases, create minimal verification code first

### Pattern 5: Insufficient Existing Code Investigation
**Symptom**: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns
**Cause**: Insufficient understanding of existing code before implementation; referencing only nearby files without checking representativeness
**Avoidance**:
- Before implementation, always search for similar functionality
- Similar functionality found: Use that implementation (do not create new)
- Similar functionality is technical debt: Create ADR improvement proposal
- No similar functionality: Implement following existing design philosophy
- When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting it

## Debugging Techniques

### 1. Error Analysis Procedure
1. Read error message (first line) accurately
2. Focus on first and last of stack trace
3. Identify first line where your code appears

### 2. 5 Whys - Root Cause Analysis
```
Example:
Symptom: Build error
Why1: Contract 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 in dependency manifest
```

### 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

### 4. Debug Log Output (temporary)
Add structured debug logs to isolate the issue, then remove them before commit.

```
Pattern: Structured logging with context
{
  context: 'operation-name',
  input: { relevant, input, data },
  state: currentState,
  timestamp: current_time_ISO8601
}
```

## Quality Assurance Mechanism Awareness

Before executing quality checks, discover applicable quality tools and constraints by inspecting the affected files' types, project manifests, CI pipelines, and configuration:
- Primary detection: inspect affected file types, manifests, configuration, and CI pipelines to identify applicable quality tools
- Check for domain-specific linters or validators such as schema validators, API spec validators, or configuration-file checkers
- Check for domain-specific constraints in project configuration such as naming rules, length limits, or format requirements
- When a task file lists `Quality Assurance Mechanisms`, use that section as supplementary guidance for what to verify
- Include discovered domain-specific checks alongside the standard quality phases below

## Quality Check Workflow [MANDATORY]

Universal quality assurance phases applicable to all languages:

### Phase 1: Static Analysis
1. **Code Style Checking**: Verify adherence to style guidelines
2. **Code Formatting**: Ensure consistent formatting
3. **Unused Code Detection**: Identify dead code and unused imports/variables
4. **Static Type Checking**: Verify type correctness (for statically typed languages)
5. **Static Analysis**: Detect potential bugs, security issues, code smells

### Phase 2: Build Verification
1. **Compilation/Build**: Verify code builds successfully
2. **Dependency Resolution**: Ensure all dependencies are available and compatible
3. **Resource Validation**: Check configuration files, assets are valid

### Phase 3: Testing
1. **Unit Tests**: Run all unit tests
2. **Integration Tests**: Run integration tests
3. **Test Coverage**: Measure coverage when configured and use it to find gaps
4. **E2E Tests**: Run end-to-end tests

### Phase 4: Final Quality Gate [MANDATORY]
All checks MUST pass before proceeding:
- Zero static analysis errors
- Build succeeds
- All tests pass
- Coverage threshold passes when the project, task file, work plan, or Design Doc defines one. When no threshold is configured, use coverage output only to identify untested critical paths.

**ENFORCEMENT**: Cannot proceed with ANY quality check failures — fix ALL errors before marking task complete

## Situations Requiring Technical Decisions

### Timing of Abstraction
- Extract patterns after writing concrete implementation 3 times (Rule of Three)
- Apply YAGNI — implement only currently needed features
- Prioritize current simplicity over future extensibility

### Performance vs Readability
- Prioritize readability unless clear bottleneck exists
- **Measure first** — profile before optimizing (no guessing)
- Document reason with comments when optimizing

### Granularity of Contracts and Interfaces
- Overly detailed contracts reduce maintainability
- Design interfaces that appropriately express domain
- Use abstraction mechanisms to reduce duplication

## Implementation Completeness Assurance

### Impact Analysis: Mandatory 3-Stage Process [MANDATORY]

Complete these stages sequentially before any implementation:

**1. Discovery** - Identify all affected code:
- Implementation references (imports, calls, instantiations)
- Interface dependencies (contracts, types, data structures)
- Test coverage
- Configuration (build configs, env settings, feature flags)
- Documentation (comments, docs, diagrams)

**2. Understanding** - Analyze each discovered location:
- Role and purpose in the system
- Dependency direction (consumer or provider)
- Data flow (origin to transformations to destination)
- Coupling strength

**3. Identification** - Produce structured report:
```
## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]

### Indirect Impact
- [System]: [Integration path and reason]

### Data Flow
[Source] -> [Transformation] -> [Consumer]

### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]

### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]
```

**ENFORCEMENT**: CANNOT implement until all 3 stages are documented

### Unused Code Deletion

When unused code is detected:
- Will it be used in this work? Yes: Implement now | No: Delete now (Git preserves)
- Applies to: Code, tests, docs, configs, assets

### Existing Code Modification

```
In use? No -> Delete
       Yes -> Working? No -> Delete + Reimplement
                     Yes -> Fix/Extend
```

**Principle**: Prefer clean implementation over patching broken code

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shinpr](https://github.com/shinpr)
- **Source:** [shinpr/codex-workflows](https://github.com/shinpr/codex-workflows)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-shinpr-codex-workflows-ai-development-guide
- Seller: https://agentstack.voostack.com/s/shinpr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.