Init Research Project

init-research-project

Generate a root CLAUDE.md plus a structured .claude/ directory so Claude has persistent context across sessions. The goal: after initialization, you should never need to re-explain project background, constraints, or infrastructure within this directory.

Core principle: conversational, not interrogational

Never dump all questions at once. Conduct the interview in rounds — at most 3 questions per round. Always use AskUserQuestion to present options. Provide smart defaults based on what the directory scan reveals and what was already answered.

Workflow

Step 0: Quick directory scan

Before asking anything, get a picture of what's already there:

ls -la
find . -maxdepth 2 -type f | grep -v "/.git/" | head -40
rg --files --hidden -g '!.git/**' -g '**/task_plan.md'

Note clues: existing README, config files, setup scripts, language-specific files (pyproject.toml, package.json, CMakeLists.txt, etc.), and any task_plan.md. Use these to pre-fill smart defaults in later questions.

Step 1: Interview (round by round)

Extract whatever the user already stated in the conversation before asking. Then proceed round by round. Each round uses AskUserQuestion with 2–3 questions max.

Round 1 — Project identity (2 questions)

Ask about project type and one-sentence goal.

• Project type (single-select): provide options relevant to what the directory scan suggests. Typical options:

  • ML/AI Research (training, inference, optimization)
  • Systems / Infra (databases, compilers, kernels)
  • Web Application (frontend, backend, full-stack)
  • Data Science / Analytics
  • Mobile / Embedded
  • Other

• One-sentence goal (single-select with templates): offer 3–4 goal templates based on the detected project type, plus "I'll write my own". Keep templates generic enough to fit most projects of that type. Examples by type:

  • ML/AI: "Train a model for [task]" / "Optimize inference on [hardware]" / "Benchmark approaches for [problem]"
  • Web: "Build a [dashboard/API/landing page] for [audience]" / "Migrate [feature] from [old stack] to [new stack]"
  • Systems: "Build a [database/compiler/proxy] that handles [workload]" / "Optimize [component] for [metric]"
  • Data Science: "Analyze [dataset] to answer [question]" / "Build a pipeline to ingest and transform [data source]"

Use the directory scan clues to make the template options as specific as possible.

Round 2 — Tech & environment (2–3 questions)

Adapt options based on the project type from Round 1.

• Primary language & frameworks (multi-select): tailor options per project type. Examples:

  • ML/AI: Python + PyTorch, Python + JAX, Python + TensorFlow, C++/CUDA, Other
  • Web: TypeScript + React, TypeScript + Vue, Python + FastAPI/Django, Go, Other
  • Systems: C++/CUDA, Rust, C, Python + C extensions, Other

• Dev environment (multi-select):

  • Local machine only
  • Remote Linux server (SSH)
  • Cloud VM (AWS/GCP/Azure)
  • Mobile / embedded device
  • CI/CD only

• Package manager (single-select):

  • conda / mamba
  • pip / venv
  • poetry / uv
  • npm / yarn / pnpm
  • cargo
  • Other

Round 3 — Remote server details (1–2 questions — skip entirely if Round 2 was "local only")

Only ask if the user indicated a remote environment.

• SSH connection: free text with a template hint — user@host
• Working directory + env setup: free text with a template hint — /home/user/project, then conda activate myenv or source venv/bin/activate

These are free-text questions, so use single-select with a "I'll type it" option and maybe 1–2 pre-filled guesses from the directory scan.

Round 4 — Operations & guardrails (2–3 questions)

• How to run / test (multi-select or single-select with templates):

  • python main.py / python train.py
  • bash scripts/run.sh
  • pytest / npm test / cargo test
  • make / cmake --build .
  • "I'll describe it"

• Protected files (multi-select): list files/dirs the directory scan found that look important (e.g. data/, config.yaml, benchmark.py), plus:

  • "Nothing needs protection"
  • "I'll specify"

• Known pitfalls (single-select):

  • "No known pitfalls yet"
  • "There are a few — I'll describe them"

Round 5 — Optional research context and roadmap (1–3 questions — skip if the user seems in a hurry)

• Baseline numbers: single-select with templates like:

  • "No baselines yet — this is exploratory"
  • "I have some numbers — I'll share them below"
  • "Skip for now"

• Key references (papers, docs, prior work): single-select:

  • "Skip for now"
  • "I'll list a few"

• Adaptive research roadmap: ask this only for a research project when the user has mentioned multi-stage work, a deadline, changing direction from evidence, or explicitly asked for a roadmap:

  • "Create and maintain it after results that can change the research direction"
  • "Create an initial roadmap only"
  • "Skip it"

If the scan already found task_plan.md or a planning-with-files plan, do not offer a separate roadmap by default. Explain that the existing plan is the source of truth, and only merge research decision gates into it with explicit permission.

Skip this round entirely when neither the optional context nor a roadmap is useful.

Round 6 — Final preferences (1 multi-select question, adapt options by project type)

Wrap up by asking if the user has any behavioral preferences they want baked into the config. This must be multi-select so the user can pick several preferences at once. Generate 3–4 options that fit the project type and the conversation so far — don't reuse the same static list every time. The goal is to surface useful defaults the user might not think to ask for.

Some inspiration (pick 3–4 that fit, or invent better ones):

Always include "No special preferences" as an option. If the user selects it alongside other preferences, treat "No special preferences" as the only selection and skip adding anything.

Write whatever the user selects into the most appropriate section of rules.md. Use a ## Workflow or ## Communication or ## Before certain operations heading as needed. If the user types a custom instruction, place it where it fits best.

If the user selects only "No special preferences", skip without adding anything.

Stopping early

If at any point the user says "just generate the files" or indicates they don't want more questions, stop the interview and use [unknown] for unanswered fields. Do not infer a roadmap request from this; generate one only when the user explicitly chose it or already asked for it.

Step 2: Generate the files

Create CLAUDE.md at project root, plus .claude/ directory with all sub-files. Print a one-line summary after creating each file.

Files to generate

CLAUDE.md — entry point (project root, NOT inside .claude/)

Write this file at the project root so Claude Code auto-loads it. All content lives in the imported sub-files.

# [Project Name]

> [One-sentence goal]

@.claude/project-statements.md
@.claude/environment.md
@.claude/rules.md
@.claude/faults.md
<!-- @.claude/references.md -->
<!-- @.claude/roadmap.md -->

Uncomment each optional import only when its corresponding file was generated.

.claude/project-statements.md

Adapt sections based on project type:

# Project Statements

## [Goal / Core Hypothesis]
[What this project is trying to achieve — specific enough that Claude can tell when a proposed approach is off-target]

## Scope
**In scope:**
- [What this project covers]

**Out of scope:**
- [Explicit exclusions — prevents Claude from "helpfully" expanding scope]

## Success Criteria
| Metric | Target | Notes |
|--------|--------|-------|
| [metric] | [value] | [how measured] |

## Deadline / Venue
- [Conference, release date, or "TBD"]

## Current Status
[One sentence: where things stand right now]

For research projects, rename "Goal" → "Core Hypothesis" and add "Venue / Submission deadline". For engineering projects, rename "Goal" → "Product Goal" and add "Non-goals".

.claude/environment.md

Generate only the sections that apply. Skip sections entirely if not relevant.

# Environment

## Local Machine
- OS: [e.g. macOS Apple Silicon / Ubuntu 22.04]
- [Any local constraints — e.g. "no GPU locally, prototyping only"]

## Remote Server  ← omit if not used
- **SSH**: `ssh [user]@[host]`
- **Working dir**: `[path]`
- **Env setup**: `[e.g. conda activate myenv / source venv/bin/activate]`

## Target Hardware  ← omit if not relevant
- **Device**: [e.g. Snapdragon 8 Gen 3 / Raspberry Pi 5]
- **Constraints**: [e.g. "8GB RAM limit", "arm64 only"]

## Tech Stack
- **Language(s)**: [e.g. Python 3.11, C++17]
- **Key frameworks**: [e.g. PyTorch 2.3, FastAPI]
- **Package manager**: [e.g. conda, pip, npm]

## How to Run
```bash
# [most common daily command]
[command]

# [second most common]
[command]

---

### `.claude/rules.md`

```markdown
# Rules

## Protected files — do not modify without explicit permission
- `[file or dir]` — [why it's protected]

## Conventions
- [Key coding or workflow conventions for this project]

## Before certain operations
- [e.g. "before changing DB schema: back up first"]

## Communication
- [e.g. "respond in Chinese", "code comments in English"]

If the user mentioned no protected files and no special conventions, keep the sections but add one sensible default (e.g. "no hardcoded credentials" for Python projects). Don't invent constraints the user didn't imply.

When the user selected “Create and maintain it”, add this under ## Workflow:

• After a completed experiment or planned review that can change the research direction, update roadmap.md with the evidence link and the resulting continue, redirect, or stop decision. Do not change direction for incomplete or invalid results.

.claude/faults.md

Only include real pitfalls — ones the user explicitly mentioned, or genuinely surprising gotchas for their specific stack. Don't pre-fill generic advice.

# Known Faults & Pitfalls

## Project-specific
<!-- Add as you discover them. Format: bold title, what happened, how you found it, the fix. -->
[Fill from user's answer, if any. Otherwise leave the comment as a prompt.]

## Common pitfalls for [tech stack]  ← omit if nothing non-obvious applies
[1–3 genuinely surprising gotchas, not generic advice]

.claude/references.md — only if user provided references

Skip entirely if no references. When generated, also uncomment @.claude/references.md in CLAUDE.md.

# Key References

| Title | Source | Relation to this project |
|-------|--------|--------------------------|
| [name] | [Author YYYY / URL / doc name] | [e.g. "baseline to beat", "method we build on"] |

<!-- Claude: when discussing approaches or comparing against baselines from this table,
     use WebFetch (arXiv, open-access) or Read (local PDF) to pull the actual paper content
     before making claims. Don't rely on the title alone. -->

.claude/roadmap.md — only if the user chose an adaptive research roadmap

Do not generate this file for non-research projects, merely because a project has a deadline, or when an existing task plan is already the agreed source of truth. It records long-range research decisions, not daily tasks or raw experiment logs.

# Research Roadmap

> Read `project-statements.md` for the durable goal, scope, and success criteria.

## Update rule
Update this file only after a completed experiment or planned review that can change the research direction. Preserve previous decisions in the history below.

## Current decision gates
| Stage | Research question / hypothesis | Largest uncertainty | Decisive experiment or evidence | Continue / redirect / stop condition | Current decision | Next review |
|-------|--------------------------------|---------------------|---------------------------------|--------------------------------------|------------------|-------------|
| [stage] | [claim to test] | [what could invalidate it] | [smallest useful test] | [quantitative or observable criterion] | [pending] | [date or trigger] |

## Decision history
| Date | New evidence | Decision | Rationale and impact |
|------|--------------|----------|----------------------|
| [date] | [link to record] | [continue / redirect / stop] | [which condition changed and what follows] |

.claude/settings.json

Start from this base and add based on the user's actual tech stack:

{
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git status)"
    ]
  }
}

Then append based on detected stack:

After generating

List the files created (one line each). Then say:

• faults.md grows in value over time — add to it whenever a new pitfall is found
• project-statements.md should be updated when goals or scope shift
• When present, roadmap.md should be updated only after evidence changes a research decision
• Run /init if you also want Claude to scan the codebase for file-level context