AI Workflows: Introduction

1. Summary

Claude Code conversations have a finite context window. Every file read, every tool call, and every response consumes tokens. When a session grows long, earlier content gets compressed or evicted and the model loses access to decisions made at the start. The remedy is to externalize important context into md files that you load at the beginning of each session.

This thread documents ten recurring development workflows, each with a corresponding md file and example prompts. The md file for each workflow encodes the goal, constraints, and conventions for that task. You hand it to Claude at session start so every response in that session is grounded in the same shared understanding.

Workflow	md File	Purpose
Small Tools	pytools.md	Quick utility scripts without restarting context each time
Spec-Driven Impl	spec.md	Lock in what before agreeing to how
Analysis	analysis.md	Understand existing code before changing it
Refactoring	refactor.md	Change structure without changing behavior
Code Smells	codesmells.md	Find structural problems before they cause failures
Vulnerabilities	vulner.md	Find security and correctness issues before they ship
Dependencies	depend.md	Map what your code relies on and what relies on it
Code Organization	codeorg.md	Restructure directories and files safely
Publish	pub.md	Readme generation, git workflow, and release prep
Text Editing	managetext.md	Edit documentation and prose without losing your voice

2. Context Limits and Session Hygiene

The context window holds everything Claude can see at once: your messages, its responses, file reads, tool call outputs, and any injected content. As a session grows, the harness compresses older turns. A long session that started with a clear goal gradually loses access to the specifics of that goal.

Two tools manage this:

/clear - resets context entirely. Use this when a session has drifted or when you are starting a genuinely different task. History is lost, but you gain a clean slate.
md files - write the important context once, reload it at session start. The session resets cleanly but retains everything that matters for that workflow.

The pattern: write a workflow md file once, load it at the start of each relevant session. Claude reads it, confirms, and every subsequent response in that session is grounded in the constraints and goals you stated.

3. Writing Effective Workflow md Files

A workflow md file is a structured prompt you write once and reuse. It is not documentation - it is an instruction set for Claude. Write it to eliminate the most common misunderstandings that arise when you start that type of work.

Four things every workflow md file should state:

Goal - one sentence stating what this session is for.
Scope - which files or modules are in play and which are out of scope.
Constraints - language version, forbidden dependencies, style rules, error conventions.
Done condition - how you will know the work is finished.

Leave anything genuinely uncertain as an explicit open question rather than letting Claude guess. A stated open question gets a conversation; a silent guess gets an assumption baked into code.

Keep md files short - a page or less. A file that takes three minutes to read consumes tokens and competes with the code you actually need in context. If you find yourself writing prose to explain the codebase broadly, that content belongs in a CLAUDE.md checked into the repo, not in a per-workflow md file.

4. Starting a Session

The opening turn of a session sets the frame for everything that follows. A well-formed opening prevents the back-and-forth that comes from Claude guessing at your constraints.

Standard opening pattern:

Read [workflow].md.

[One sentence stating the specific task for this session.]

Do not start implementing until I approve your plan.

The "do not start" instruction matters. Without it, Claude may produce several screens of code before you have corrected its interpretation of the task. A plan is cheap to discard; half-written code is not. Skip this instruction only when the task is small enough that a one-shot attempt costs nothing to revise.

Within a session, the conversation patterns documented in AI Bites: Prompt Patterns apply across all of these workflows. A spec-driven session might use Decomposition to step through implementation one piece at a time; an analysis session might use Chain-of-Thought to make the model's reasoning explicit; a refactoring session might use Self-Critique to catch scope creep in the model's own plan. The md file establishes the context for a session; prompt patterns govern the structure of individual exchanges within it.

5. When to Create a New Workflow md File

Create a workflow md file when you find yourself repeating the same setup text at the start of sessions on the same type of task. If the second session on a topic opens with the same constraints you stated in the first, pull those constraints into an md file.

The md files in this thread are starting points. Edit them for your codebase. The spec.md template is generic - add the specific language version, your error-handling convention, and the names of the modules in scope for your project. A workflow md file that names your actual files is more useful than a generic template.