Feature Development Workflow

Most people use AI code agents the same way: describe a feature, hit enter, hope for the best. Sometimes it works. Often you get something that technically runs but misses half the requirements, ignores your existing patterns, and needs a full rewrite.

This workflow fixes that by breaking feature development into seven phases. The agent understands the codebase before writing code, asks you questions before making assumptions, and proposes architecture before implementing anything. It takes longer per feature, but you stop throwing away the output.

The seven phases

1. Discovery — Understand what needs to be built. If the request is vague, ask the user what problem they’re solving, what the feature should do, and any constraints.

2. Codebase exploration — Read existing code before writing new code. Find similar features, trace their implementation, map the architecture. This is where most workflows fail: they skip straight to writing code without understanding what’s already there.

3. Clarifying questions — After exploring the codebase, identify every ambiguity: edge cases, error handling, integration points, scope boundaries, backward compatibility. Present all questions to the user and wait for answers. Do not skip this phase.

4. Architecture design — Propose 2-3 implementation approaches with different trade-offs. Minimal changes (smallest diff, maximum reuse), clean architecture (maintainability first), or pragmatic balance. Recommend one and explain why. Ask the user which approach they prefer.

5. Implementation — Build the feature following the chosen architecture. Do not start without explicit user approval. Follow existing codebase conventions.

6. Quality review — Review the implementation for simplicity, bugs, and convention compliance. Present findings and let the user decide what to fix now vs. later.

7. Summary — Document what was built, key decisions, files modified, and suggested next steps.

The SKILL.md

Here’s the full skill. Copy the directory into your editor’s skills folder (see installation below).

---
name: feature-dev
description: Guided feature development with codebase exploration, clarifying questions, and architecture design before implementation. Use when building a new feature, implementing something that touches multiple parts of the codebase, or when the user asks for a structured feature build.
metadata:
  author: agent-config
  version: "1.0"
---

# Feature development workflow

You are helping a developer implement a new feature. Follow a systematic
approach: understand the codebase, identify and ask about all underspecified
details, design architecture, then implement.

## Principles

- Ask clarifying questions. Identify all ambiguities, edge cases, and
  underspecified behaviors. Ask specific questions rather than making
  assumptions. Wait for answers before proceeding. Ask early, before
  designing architecture.
- Understand before acting. Read existing code patterns first.
- Simple and elegant. Prioritize readable, maintainable code.

## Phase 1: Discovery

Understand what needs to be built.

1. If the feature is unclear, ask the user:
   - What problem are they solving?
   - What should the feature do?
   - Any constraints or requirements?
2. Summarize understanding and confirm with the user.

## Phase 2: Codebase exploration

Understand relevant existing code and patterns.

1. Find similar features and trace their implementation.
2. Map the architecture: abstractions, layers, flow of control.
3. Identify UI patterns, testing approaches, and extension points.
4. List the 5-10 most important files for context.
5. Present a summary of findings and patterns discovered.

## Phase 3: Clarifying questions

CRITICAL: Do not skip this phase.

1. Review codebase findings and the original feature request.
2. Identify underspecified aspects: edge cases, error handling,
   integration points, scope boundaries, design preferences,
   backward compatibility, performance needs.
3. Present all questions in a clear, organized list.
4. Wait for answers before proceeding to architecture.

If the user says "whatever you think is best", provide your recommendation
and get explicit confirmation.

## Phase 4: Architecture design

Design multiple implementation approaches with different trade-offs.

1. Consider at least two approaches:
   - Minimal changes: smallest diff, maximum reuse of existing code
   - Clean architecture: maintainability and good abstractions
2. Present trade-offs, your recommendation with reasoning, and concrete
   implementation differences.
3. Ask the user which approach they prefer.

## Phase 5: Implementation

Do not start without user approval.

1. Implement following the chosen architecture.
2. Follow codebase conventions.
3. Write clean, well-documented code.

## Phase 6: Quality review

1. Review the implementation for:
   - Simplicity and DRY violations
   - Bugs and functional correctness
   - Project convention compliance
2. Present findings to the user.
3. Ask what they want to do: fix now, fix later, or proceed as-is.

## Phase 7: Summary

1. Summarize what was built.
2. List key decisions made.
3. List files modified.
4. Suggest next steps.

Usage

The clarifying questions phase (Phase 3) is the single biggest improvement over “just build it.” Most feature requests are underspecified. When an agent guesses at edge cases, it guesses wrong about half the time. Forcing it to ask first means you catch misunderstandings before they become code.

The codebase exploration phase is the second biggest win. Without it, agents default to whatever patterns they picked up from training data. With it, they follow your project’s actual conventions.

Customize it for your project:

• Add a “run tests” step to Phase 5 if you have a test suite.
• Add a “check types” step if you’re using TypeScript.
• Remove Phase 4 (architecture) for small, self-contained changes.
• Add project-specific questions to Phase 3 (e.g., “does this need a migration?”).
• Pair it with the code simplifier as a cleanup pass after Phase 5.

.claude/skills/feature-dev/SKILL.md    # Claude Code
.cursor/skills/feature-dev/SKILL.md    # Cursor

~/.claude/skills/feature-dev/SKILL.md