Status: Complete (v1.0)

Overview

Research code doesn’t have to be garbage.

A complete system for building production-grade research software using AI agents. This framework addresses the fundamental problem that research code defaults to being terrible—no tests, no validation, no reproducibility, results that can’t be trusted.

Why does this happen? Scientists and AI agents both optimize for “code that compiles,” not “code that’s correct.”

The 5 Core Principles

  1. Correctness First — Physical accuracy is non-negotiable
  2. Specification Before Code — Tests define the contract
  3. Fail Fast with Clarity — Validate at boundaries, error immediately
  4. Simplicity by Design — Each function does one thing
  5. Infrastructure Enables Speed — Tests, CI/CD, and tooling aren’t overhead

Who This Is For

  • PhD students learning to code scientifically
  • Researchers pairing Claude/ChatGPT with their work
  • Labs wanting to enforce quality without micromanaging
  • Anyone tired of inheriting garbage research code

Key Components

Documentation

FilePurpose
research-code-principles.mdPhilosophy: why good code matters
style-guide-reference.mdStandards: C++, Python, CMake, testing
repo-standards.mdWorkflow: git, CI/CD, infrastructure
agent-coding-context.mdPaste into Claude for coding sessions
prompting-research-code.mdHow to prompt for research-grade code

OpenCode Context Manager

Reduce token usage by 60-70% when loading documentation into AI sessions.

Instead of loading entire 50k+ token doc files, use vector search to load only relevant chunks:

# Load all docs from a directory (~20k tokens instead of 60k)
oc-context --all ./agent_docs

# Semantic search for specific topics
oc-context --query "error handling validation"

The tool uses vector embeddings and semantic search to retrieve only the relevant sections of your documentation, dramatically reducing context window usage while maintaining quality.

Using With AI Agents

  1. Paste docs/agent-coding-context.md into your session
  2. Reference docs/prompting-research-code.md for patterns
  3. Provide one working example (few-shot)
  4. Use Chain of Thought: “Think step by step about edge cases, then write tests, then implement”

Examples

The repository includes a complete quantum gate implementation example demonstrating:

  • Test-first development
  • Physical validation
  • Error handling
  • Documentation standards

Technology Stack

  • Documentation: Markdown with structured templates
  • Context Manager: Python, vector embeddings, semantic search
  • Examples: C++, Python with pytest

Motivation

This framework emerged from my experience building research software for quantum computing projects. The principles and tooling here are battle-tested across multiple codebases with 800+ unit tests, CI/CD pipelines, and production-quality standards.

The goal: make it easier for researchers to write code that actually works, and make it easier for AI agents to help them do it correctly.