코덱스 - 비개발자편

# AGENTS.md

## Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

- State your assumptions explicitly.
- If uncertain, ask.
- If something is unclear, stop. Name what's confusing. Ask.
- For meaningful choices, explain the tradeoff before choosing.
- For minor choices, pick a reasonable default and continue.

## Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No speculative configuration.
- No compatibility layers unless explicitly requested.
- If the solution is much larger than the problem, simplify it.

## Surgical Changes

Touch only what you must. Clean up only your own mess.

- Every changed line should trace directly to the user's request.
- Don't refactor things that aren't broken.
- Don't reformat unrelated code.
- Don't rename unrelated symbols.
- Match existing style, even if you'd do it differently.
- Remove only dead code created by your ow

---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "S

---
name: problem-solving
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Problem Solving

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't completed Phase 0 and Phase 1, you cannot propose fixes.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when

---
name: verify-before-done
description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
---

# Verify Before Done

## Overview

Claiming work is complete without verification is dishonesty, not efficiency.

**Core principle:** Evidence before claims, always.

**Violating the letter of this rule is violating the spirit of this rule.**

## The Iron Law

```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```

If you haven't run the verification command in this message, you cannot claim it passes.

## The Gate Function

```
BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with

---
name: executing-action-plans
description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
---

# Executing Action Plans

## Overview

Load plan, review critically, execute all tasks, report when complete.

**Announce at start:** "I'm using the executing-plans skill to implement this plan."

**Note:** Tell your human partner that Superpowers works much better with access to subagents. If subagents are available, use `subagent-driven-development` instead of this command. If they are unavailable, execute inline with checkpoints.

## The Process

### Step 1: Load and Review Plan
1. Read plan file
2. Review critically - identify any questions or concerns about the plan
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Create todos for the plan items and proceed

### Step 2: Execute Tasks

For each task:
1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verific

---
name: parallel-tasks
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
---

# Parallel Tasks

## Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

## When to Use

```dot
digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [sha

---
name: receiving-feedback
description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
---

# Receiving Feedback

## Overview

Code review requires technical evaluation, not emotional performance.

**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.

## The Response Pattern

```
WHEN receiving code review feedback:

1. READ: Complete feedback without reacting
2. UNDERSTAND: Restate requirement in own words (or ask)
3. VERIFY: Check against codebase reality
4. EVALUATE: Technically sound for THIS codebase?
5. RESPOND: Technical acknowledgment or reasoned pushback
6. IMPLEMENT: One item at a time, test each
```

## Forbidden Responses

**NEVER:**
- "You're absolutely right!" (explicit instruction-file violation)
- "Great point!" / "Excellent 

---
name: task-planning
description: Use when work has multiple steps, unclear requirements, meaningful risk, or several possible approaches and execution should wait for explicit confirmation.
---

# Task Planning

Plan before acting. Restate the goal, define success, surface tradeoffs, identify risks, and wait for explicit approval before executing.

## When to Use

- Starting a new project or initiative
- Work that involves multiple steps or people
- Requirements are unclear or ambiguous
- Multiple approaches are possible
- High stakes (presentation, launch, campaign, report)
- You need a lightweight plan, not a full implementation spec

## The Process

1. **Restate Requirements** - Clarify what needs to be accomplished in your own words.
2. **State Assumptions** - Name defaults you are choosing and uncertainties that remain.
3. **Define Success Criteria** - What proves this is done? Include verification method.
4. **Compare Approaches** - For meaningful choices, present 2-3 options

---
name: writing-action-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---

# Writing Action Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.

**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for pl

---
name: extract-insights
description: Use after a non-trivial session reveals a reusable workflow, failure pattern, decision rule, or tool combination worth preserving for future work.
---

# Extract Insights

Capture reusable lessons from a session so future work starts with evidence instead of rediscovery.

## When to Use

Run this near the end of a session when:

- A problem took multiple attempts to solve.
- A non-obvious workflow or tool combination worked.
- A failure pattern should be avoided next time.
- A decision framework emerged from tradeoffs.
- The insight applies across projects, not only to one incident.

Do not extract trivial steps, one-off outage details, or facts already documented in project instructions.

## Insight Selection

Pick one insight per note. A good insight has:

- **Trigger:** when a future agent should remember it.
- **Pattern:** what to do or avoid.
- **Evidence:** what happened that proves the pattern matters.
- **Boundary:** when not to apply it.

---
name: handoff
description: Use when context is getting full, a session needs to continue elsewhere, or plan execution must be resumed later without losing state.
---

# Handoff - Session Transfer

Create a compact, actionable transfer note so a new session can continue without rediscovering decisions, files, blockers, or plan progress.

## When to Use

- Context is getting heavy or compaction is likely.
- You need to stop but want the next session to continue.
- Work is mid-plan and task status matters.
- A different person or agent will pick up the work.

## The Rule

The next session needs operational state, not a diary. Capture what changed, what is true now, what remains, and the exact first next action.

## What to Capture

1. **Objective** - the user's end goal, not just the last task.
2. **Working directory** - absolute path and target repo/project.
3. **Active plan** - path to the plan/spec if one exists, plus completed and remaining tasks.
4. **Git state** - branch, latest