สถานะ: 🟢 Complete — อัพเดท: 2026-06-28

AI-Assisted Software Development Workflow

Philosophy

The purpose of this workflow is not simply to use AI Skills, but to reduce development cost by discovering problems as early as possible (Shift Left).

Each phase has one responsibility only. A phase should never perform the job of another phase.

Scope

This workflow covers:

New feature development
Bug fixes (via Incident Workflow)

This workflow does not cover:

Refactoring
Team collaboration (solo developer + AI only)

Starting Point

Situation	Phase 1 Tool
New project — no CONTEXT.md exists	`grill-me` → creates CONTEXT.md from scratch
Existing project — CONTEXT.md exists	`grill-with-docs` → cross-checks against existing domain

Overall Workflow

flowchart TD
    START{{"Starting Point"}}
    START -->|"No CONTEXT.md"| GRILL["grill-me\nCreate CONTEXT.md from scratch"]
    START -->|"CONTEXT.md exists"| GRILLDOCS["grill-with-docs\nCross-check against existing domain"]

    GRILL --> P1
    GRILLDOCS --> P1

    P1["🔍 Phase 1 — Discovery\ngrill-with-docs"]
    P2["📐 Phase 2 — Design Review\nplan mode → scrutinize"]
    P3["📋 Phase 3 — Implementation Planning\nkarpathy-guidelines"]
    P4["⚙️ Phase 4 — Implementation\nkarpathy-guidelines"]
    P5["✅ Phase 5 — Validation\ncode-review → scrutinize?"]

    P1 --> P2 --> P3 --> P4 --> P5

    P5 -->|PASS| MERGE["🚀 Merge / Release"]

    P5 -->|"FAIL: Coding Issue"| P4
    P5 -->|"FAIL: Planning Issue"| P3
    P5 -->|"FAIL: Design Issue"| P2
    P5 -->|"FAIL: Requirement Issue"| P1

Phase 1 — Discovery

Tool

grill-with-docs

Objective

Understand the problem completely before discussing implementation.

The AI should discover the business problem rather than immediately designing a solution.

Responsibilities

Clarify requirements
Discover business rules
Explore edge cases
Build shared language
Update CONTEXT.md
Create ADRs when necessary — use this test:

“Would a future developer reasonably make a different choice here, and would that choice cause real pain to reverse?” If YES → write an ADR. If NO → skip it.

Deliverables

Complete requirements
CONTEXT.md
ADRs
Shared terminology

Exit Criteria

Requirements are clear
No unanswered business questions, or unresolvable questions are documented as explicit assumptions in CONTEXT.md and flagged as unverified
Shared language established

Why?

Requirement mistakes are the most expensive mistakes to discover late.

Fixing requirements before coding is dramatically cheaper than rewriting code later.

Phase 2 — Design Review

Tool

Step 1: plan mode   → propose architecture / design
Step 2: scrutinize  → attack the proposed design

Objective

Attack the proposed design.

This phase reviews architecture—not code.

Responsibilities

Step 1 — plan mode produces:

Architecture proposal
Database schema
API design
Key design decisions

Step 2 — scrutinize challenges:

Architecture
Database design
API design
Security
Scalability
Performance
Concurrency
Edge cases

Deliverables

Improved architecture
Design corrections
Identified risks

Exit Criteria

No major architectural concerns remain

Major = any concern that cannot be fixed by changing code alone:

Schema changes
API contract changes
Security architecture changes
Race conditions
Missing constraints

Not major (fix in Phase 4):

Performance tuning
Code style
Naming
Index optimization

Why?

Correct requirements do not guarantee a good design.

Example:

Requirement: Recurring payments.

Poor design: Run cron every minute.

Better design: Dedicated scheduler.

Requirements stay the same. Only the design changes.

Phase 3 — Implementation Planning

Tool

karpathy-guidelines

Objective

Think before coding.

This phase converts the approved design into an implementation plan.

Responsibilities

Produce:

PLAN.md
Task breakdown
File modification list
Migration strategy
Rollback strategy
Testing strategy
Implementation phases
Commit strategy (one commit per logical task in the breakdown)

Deliverables

Approved implementation plan

Exit Criteria

Developer approves the implementation plan
Risks identified
Tasks clearly ordered

Why?

Many developers jump directly from design to code.

Planning significantly reduces:

forgotten files
missing migrations
missing tests
poor commit structure
poor rollback strategy

Phase 4 — Implementation

Tool

karpathy-guidelines

Objective

Execute the plan.

Avoid redesigning during implementation.

If implementation reveals the design is wrong — stop. Return to Phase 2. Do not make design decisions in Phase 4. Do not document deviations and continue. Any unplanned design change is a Phase 2 issue.

Responsibilities

Coding
Unit tests:
- Non-trivial logic only (a branch, a loop, a parser, a money/security path)
- One small test that fails if the logic breaks
- No frameworks, no fixtures, no per-function suites
- Trivial one-liners need no test
Documentation:
- Inline comments only where the WHY is non-obvious
- Update CONTEXT.md if implementation revealed new domain knowledge
- Nothing else

Deliverables

Working implementation

Exit Criteria

Feature completed
Tests passing
Documentation updated

Why?

Karpathy’s principles apply throughout implementation:

Understand first
Think first
Make minimal changes
Verify everything
Never guess

Phase 5 — Validation

Tool

Step 1: code-review            → mandatory
Step 2: scrutinize             → conditional

When to run scrutinize:

code-review passes but something still feels off
Implementation was complex and design drift is a real risk
A fundamental approach question remains unanswered

Objective

Review the implementation.

Unlike Phase 2, this reviews the actual code instead of the design.

Responsibilities

Review:

Code quality
Test coverage
Regression risk
Security
Maintainability
Missing edge cases
Consistency with design

Deliverables

PASS

FAIL with issue classification.

Exit Criteria

Implementation is production-ready
Delete PLAN.md after validation passes

If Validation Fails

Never restart the whole workflow.

Instead, classify the problem and return to the responsible phase.

Issue Type	Examples	Return To
Coding Issue	Missing null check, error handling, code smell, missing tests	Phase 4
Planning Issue	Missing migration, missing rollback plan, poor testing strategy	Phase 3
Design Issue	Wrong schema, bad API, race condition, security flaw	Phase 2
Requirement Issue	Incorrect business rules, missing requirement, wrong assumptions	Phase 1

Incident Workflow (Bug Found)

Bugs are not part of the development workflow.

They follow a separate Incident Workflow.

flowchart TD
    BUG["🐛 Bug Found"]
    DEBUG["Debug Mantra\nReproduce → Trace path → Falsify → Record"]
    ROOT["Find Root Cause"]
    CLASSIFY{"Classify Root Cause"}

    BUG --> DEBUG --> ROOT --> CLASSIFY

    CLASSIFY -->|"Requirement Problem"| RP1["Return Phase 1"]
    CLASSIFY -->|"Design Problem"| RP2["Return Phase 2"]
    CLASSIFY -->|"Planning Problem"| RP3["Return Phase 3"]
    CLASSIFY -->|"Coding Problem"| RP4["Return Phase 4"]

    RP1 & RP2 & RP3 & RP4 --> P5["Phase 5 — scoped to fix only\ncode-review on changed files\nscrutinize if design drift suspected"]

    P5 --> MERGE["🚀 Merge / Release"]
    MERGE --> IMPROVE["📈 Improve Workflow"]

Debug Mantra

Tool

debug-mantra

Purpose:

Find the Root Cause, not the Fix.

Follow the four-step discipline:

Reproduce reliably
Know the fail path
Falsify hypotheses
Record every experiment

Only after identifying the root cause should a fix be implemented.

Continuous Improvement

Every bug should improve the workflow.

Never stop at:

“How do we fix this bug?”

Also ask:

“Why didn’t our workflow catch it?”

Examples:

Race condition discovered → Validation lacked concurrency testing → Add concurrency checklist

Requirement misunderstanding → Discovery failed to ask the right questions → Improve grill-with-docs prompts

Migration failure → Planning lacked rollback strategy → Update planning template

Workflow Improvement Log

Status: Needs deeper discussion before finalizing. Notes captured here are intentions, not finalized process.

Open Questions

Where exactly do improvements land? (This file? CLAUDE.md? A separate IMPROVEMENTS.md?)
Who is responsible for writing the improvement before closing an incident?
How do we prevent the same improvement from being noted twice?
Do improvements need a review step before being merged into the workflow?

Captured Improvements

Date	Trigger	Gap Identified	Proposed Fix	Status
—	—	Incident Workflow had no capture mechanism	Add this log	Pending discussion

Guiding Principles

1. Shift Left

Find problems as early as possible.

Earlier discovery means lower cost.

2. Single Responsibility

Each phase has exactly one purpose.

Discovery discovers.
Design Review critiques architecture.
Planning plans.
Implementation builds.
Validation reviews implementation.
Debugging finds root causes.

CONTEXT.md is a living document. Any phase that discovers new domain knowledge, changes a business rule, or resolves an open question must update CONTEXT.md before exiting — not just Phase 1.

3. Stage Gates

Every phase must satisfy its exit criteria before moving forward.

No phase should continue with unresolved critical issues.

Owner: The developer makes the final call to exit a phase. The AI must surface all unresolved items before the developer exits. The AI must not silently allow a phase to close with open questions.

Context: Clear the context window at every phase boundary. Each phase starts fresh with only the relevant artifacts as input:

Entering Phase	Bring in
Phase 2	CONTEXT.md, ADRs
Phase 3	CONTEXT.md, approved design doc
Phase 4	CONTEXT.md, PLAN.md
Phase 5	CONTEXT.md, PLAN.md, the diff / changed files

4. Feedback Loop

Validation and Debugging never restart the entire process.

Instead, identify the true source of the problem and return only to the responsible phase.

5. Continuous Improvement

Every defect should improve:

the workflow
the checklist
CONTEXT.md
planning templates
prompts
AI instructions

The goal is not merely fixing today’s bug, but preventing the same class of bugs from occurring again.

Claude KnowHow

รายการหน้า

AI-Assisted Development Workflow

AI-Assisted Software Development Workflow

Philosophy

Scope

Starting Point

Overall Workflow

Phase 1 — Discovery

Tool

Objective

Responsibilities

Deliverables

Exit Criteria

Why?

Phase 2 — Design Review

Tool

Objective

Responsibilities

Deliverables

Exit Criteria

Why?

Phase 3 — Implementation Planning

Tool

Objective

Responsibilities

Deliverables

Exit Criteria

Why?

Phase 4 — Implementation

Tool

Objective

Responsibilities

Deliverables

Exit Criteria

Why?

Phase 5 — Validation

Tool

Objective

Responsibilities

Deliverables

Exit Criteria

If Validation Fails

Incident Workflow (Bug Found)

Debug Mantra

Tool

Continuous Improvement

Workflow Improvement Log

Open Questions

Captured Improvements

Guiding Principles

1. Shift Left

2. Single Responsibility

3. Stage Gates

4. Feedback Loop

5. Continuous Improvement

มุมมองกราฟ

สารบัญ

หน้าที่กล่าวถึง