Redesign around web-based Claude Code workflow
Instead of a CLI the user runs separately, this is now two files you drop into any repo: - CLAUDE.md: read automatically by Claude Code, teaches it to scan first, commit often, and leave handoff notes when usage runs low - scan.py: standalone script Claude runs itself to find errors via linters/tests/type-checkers, using zero AI tokens No workflow change for the user — they type in Claude Code as before. https://claude.ai/code/session_01Fzv8baXnEVVhnrffAb3Ucc
This commit is contained in:
Claude
@@ -1,159 +1,113 @@
|
||||
# Claude Task Chunker (`ctc`)
|
||||
# Claude Task Chunker
|
||||
|
||||
Break large coding tasks into self-contained chunks for efficient Claude Code sessions. Stop running out of usage mid-task.
|
||||
Save Claude Code usage on large codebases. Two files you drop into any repo.
|
||||
|
||||
## The Problem
|
||||
|
||||
You ask Claude Code to make a big change — add auth, refactor a module, fix errors across a 10,000-line codebase — and it runs out of usage halfway through. You're left with half-finished work and no easy way to pick up where you left off.
|
||||
You ask Claude Code to fix errors or add a feature to a big codebase. It spends
|
||||
half your usage just *reading files to find the problem*, then runs out before
|
||||
it finishes the fix.
|
||||
|
||||
## The Solution
|
||||
|
||||
Two things working together:
|
||||
Two files you copy into your project repo:
|
||||
|
||||
1. **`ctc scan`** — Runs linters, tests, and pattern matching on your codebase *without using any AI tokens*. Finds the errors so Claude doesn't have to read 10,000 lines to find them itself.
|
||||
2. **`ctc plan`** — Breaks big tasks into self-contained chunks with ready-to-paste prompts for Claude Code.
|
||||
3. **`ctc init`** — Drops a `CLAUDE.md` into your repo that teaches Claude Code to be usage-efficient automatically.
|
||||
| File | What it does |
|
||||
|------|-------------|
|
||||
| `CLAUDE.md` | Claude reads this automatically every session. It teaches Claude to scan first, stay focused, commit often, and leave a handoff note if usage runs low. |
|
||||
| `scan.py` | A script Claude runs itself to find errors. It calls your project's linters, tests, and type checkers — zero AI tokens used. |
|
||||
|
||||
## Install
|
||||
## Setup (one time per project)
|
||||
|
||||
1. Copy `CLAUDE.md` and `scan.py` into the root of your project repo
|
||||
2. Edit the "Project-Specific Commands" section in `CLAUDE.md` if needed
|
||||
3. Commit them
|
||||
|
||||
```bash
|
||||
# Clone this repo, then:
|
||||
pip install -e .
|
||||
cp /path/to/claude-task-chunker/CLAUDE.md /path/to/your-project/
|
||||
cp /path/to/claude-task-chunker/scan.py /path/to/your-project/
|
||||
cd /path/to/your-project
|
||||
git add CLAUDE.md scan.py
|
||||
git commit -m "Add Claude Code efficiency tools"
|
||||
```
|
||||
|
||||
## Quick Start: The Workflow
|
||||
That's it. You never touch these files again.
|
||||
|
||||
### Step 1: Set up your project (one time)
|
||||
## How You Use It
|
||||
|
||||
```bash
|
||||
cd /path/to/your/big-project
|
||||
ctc init
|
||||
```
|
||||
Your workflow doesn't change. You type in Claude Code exactly like before.
|
||||
|
||||
This creates a `CLAUDE.md` in your project that teaches Claude Code to work efficiently — chunk its own work, commit often, and not waste tokens exploring.
|
||||
|
||||
### Step 2: Find errors fast (no AI needed)
|
||||
|
||||
```bash
|
||||
ctc scan
|
||||
# or with a specific focus:
|
||||
ctc scan "authentication is broken"
|
||||
```
|
||||
|
||||
This runs your project's linters, tests, and type checkers automatically. It detects what kind of project you have (Python, Node, Rust, Go) and runs the right tools. The output goes to `.claude-chunks/scan_results.md`.
|
||||
|
||||
### Step 3: Open Claude Code and paste the results
|
||||
|
||||
Open Claude Code connected to your repo as normal. Then:
|
||||
### Finding and fixing errors
|
||||
|
||||
```
|
||||
Fix the errors in .claude-chunks/scan_results.md
|
||||
You: "Find and fix the errors in this codebase"
|
||||
```
|
||||
|
||||
Claude reads the pre-scanned results and goes straight to fixing — no wasted tokens reading 10,000 lines to find the bugs.
|
||||
Claude (because it read CLAUDE.md) will automatically:
|
||||
1. Run `python scan.py` — gets linter/test/type errors in seconds
|
||||
2. Read only the files with errors
|
||||
3. Fix them
|
||||
4. Commit
|
||||
|
||||
### Step 4: For big tasks, plan chunks first
|
||||
Without CLAUDE.md, Claude would read file after file trying to find the problems,
|
||||
burning through your usage.
|
||||
|
||||
```bash
|
||||
ctc plan "Add OAuth2 authentication with login, logout, and RBAC"
|
||||
```
|
||||
|
||||
This creates numbered prompt files in `.claude-chunks/prompts/`. Each one is a self-contained session:
|
||||
|
||||
```bash
|
||||
ctc next # see the next chunk's prompt
|
||||
ctc next -c # copy it to clipboard
|
||||
```
|
||||
|
||||
Open Claude Code, paste the prompt, let it work, then:
|
||||
|
||||
```bash
|
||||
ctc done 1 # mark chunk 1 complete
|
||||
ctc next # get chunk 2
|
||||
```
|
||||
|
||||
## Your Actual Workflow
|
||||
|
||||
Here's what this looks like day-to-day:
|
||||
### Big features
|
||||
|
||||
```
|
||||
You: cd my-big-project
|
||||
You: ctc scan # 10 seconds, finds 3 errors
|
||||
You: [open Claude Code]
|
||||
You: "Fix the errors in .claude-chunks/scan_results.md"
|
||||
Claude: [reads the file, fixes the 3 errors, done in one session]
|
||||
You: "Add OAuth2 authentication with login, logout, and role-based access"
|
||||
```
|
||||
|
||||
For big features:
|
||||
Claude (because it read CLAUDE.md) will automatically:
|
||||
1. Plan which files to change before coding
|
||||
2. Work through the plan, committing after each piece
|
||||
3. If usage runs low, commit what's done and create `.claude-handoff.md`
|
||||
|
||||
If it does run out, your next session you just say:
|
||||
|
||||
```
|
||||
You: ctc plan "migrate database from MySQL to Postgres" -s phase
|
||||
You: ctc next -c # copies chunk 1 prompt
|
||||
You: [open Claude Code, paste]
|
||||
Claude: [does chunk 1: research & plan, commits]
|
||||
You: ctc done 1
|
||||
You: ctc next -c # copies chunk 2 prompt
|
||||
You: [paste into Claude Code — same session or new one]
|
||||
Claude: [does chunk 2: core implementation, commits]
|
||||
You: ctc done 2
|
||||
... and so on
|
||||
You: "Continue the work described in .claude-handoff.md"
|
||||
```
|
||||
|
||||
## Commands
|
||||
And Claude picks up right where it left off — no wasted tokens re-discovering
|
||||
what was already done.
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `ctc init` | Add CLAUDE.md to your project (teaches Claude to be efficient) |
|
||||
| `ctc scan` | Find errors with linters/tests (no AI tokens used) |
|
||||
| `ctc scan "description"` | Same, but adds your description to the output prompt |
|
||||
| `ctc plan <task>` | Break a big task into chunks |
|
||||
| `ctc plan <task> -s component` | Chunk by directory/module instead of phase |
|
||||
| `ctc plan <task> -s manual --chunks-file chunks.txt` | Use your own chunk list |
|
||||
| `ctc status` | See progress on current plan |
|
||||
| `ctc next` | Print the next chunk's prompt |
|
||||
| `ctc next -c` | Copy it to clipboard |
|
||||
| `ctc done <id>` | Mark a chunk as complete |
|
||||
| `ctc show <id>` | View a specific chunk's prompt |
|
||||
|
||||
## What `ctc scan` Detects
|
||||
## What `scan.py` Detects
|
||||
|
||||
It auto-detects your project type and runs the right tools:
|
||||
|
||||
| Project | What it runs |
|
||||
|---------|-------------|
|
||||
| **Python** | pytest, ruff, mypy, syntax check |
|
||||
| **Node/TypeScript** | npm/yarn test, eslint, tsc --noEmit |
|
||||
| **Rust** | cargo check, cargo test --no-run |
|
||||
| **Go** | go build, go vet, go test |
|
||||
| **Any** | grep for TODO/FIXME/HACK/BUG markers |
|
||||
| Python | pytest, ruff, mypy, syntax check |
|
||||
| Node/TypeScript | npm/yarn test, eslint, tsc --noEmit |
|
||||
| Rust | cargo check, cargo test --no-run |
|
||||
| Go | go build, go vet, go test |
|
||||
|
||||
## Decomposition Strategies
|
||||
## Customizing CLAUDE.md
|
||||
|
||||
### `phase` (default)
|
||||
Breaks work into: Research & Plan -> Core Implementation -> Tests -> Integration & Cleanup.
|
||||
The `CLAUDE.md` file has a section at the bottom for project-specific commands.
|
||||
Edit it to match your project:
|
||||
|
||||
### `component`
|
||||
One chunk per top-level directory. Good when changes are spread across independent modules.
|
||||
```markdown
|
||||
## Project-Specific Commands
|
||||
|
||||
### `manual`
|
||||
You write a text file with one chunk per line:
|
||||
|
||||
```
|
||||
# chunks.txt
|
||||
Set up database models for users and roles
|
||||
Build registration and login API endpoints
|
||||
Add JWT middleware and session management
|
||||
Build role-based access control decorators
|
||||
# Run tests: pytest -x
|
||||
# Lint: ruff check . --fix
|
||||
# Build: docker compose build
|
||||
# Type check: mypy src/
|
||||
```
|
||||
|
||||
```bash
|
||||
ctc plan "Add user auth" -s manual --chunks-file chunks.txt
|
||||
You can also add any other instructions you want Claude to follow in every
|
||||
session — coding style, architecture decisions, files to avoid, etc.
|
||||
|
||||
## What's in this repo
|
||||
|
||||
```
|
||||
CLAUDE.md — Template to copy into your projects
|
||||
scan.py — Scanner script to copy into your projects
|
||||
README.md — You're reading it
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- **Always `ctc scan` before asking Claude to fix errors** — saves huge amounts of usage
|
||||
- **`ctc init` once per project** — the CLAUDE.md stays in the repo and works every session
|
||||
- **Keep chunks independent** — the less each chunk depends on others, the cleaner the handoff
|
||||
- **Add `.claude-chunks/` to `.gitignore`** — it's working state, not source code
|
||||
- **Commit CLAUDE.md to your repo** — it benefits every Claude Code session in that project
|
||||
The `claude_task_chunker/` directory contains an optional CLI tool (`ctc`) for
|
||||
manually planning and tracking chunks from the terminal. Most users won't need
|
||||
it — the CLAUDE.md + scan.py approach handles everything automatically.
|
||||
|
||||
Reference in New Issue
Block a user