Project OS: A Spec-Driven Development Scaffold for Claude Code

Project OS is an open-source development scaffold designed specifically for Claude Code, providing spec-driven development workflows, a memory system, sub-agent orchestration, and quality gate mechanisms.

With the popularity of AI coding assistants like Claude Code, the way developers collaborate with AI is undergoing a fundamental transformation. However, many teams find that simply letting AI "help write code" does not fully unleash its potential. AI collaboration without a structured process often leads to context loss, unstable quality, and difficulty in scaling and other issues.

Project OS was created to address these problems. It is a development scaffold designed specifically for Claude Code, combining the concept of Spec-Driven Development with AI-assisted programming to provide teams with a reusable and extensible collaboration framework.

Spec-Driven Development is a methodology that emphasizes definition before implementation. In the context of Project OS, this means:

1. Write specs first, then code: Before implementing any feature, there must be a clear, verifiable spec document
2. Specs as tests: The specs themselves include acceptance criteria and can be directly converted into test cases
3. Specs as documentation: Spec documents serve both human developers and AI assistants, ensuring consistent understanding between both parties
4. Specs as collaboration interface: Different roles (product managers, developers, AI) collaborate through specs

AI assistants (like Claude Code) perform best when handling structured inputs. Clear specs provide AI with:

• Clear context: Reduces guesswork and assumptions
• Verifiable goals: Knows what the "completion" standard is
• Consistent format: Easy to parse and process
• Traceable changes: Spec versions correspond to code versions

Project OS's architecture revolves around four core modules, forming a complete development support system.

The workflow pipeline defines the complete process from requirements to delivery, breaking down the development process into a series of clear stages:

Requirements Analysis Phase:

• Input: Raw requirements or user stories
• Processing: AI-assisted analysis to extract key requirement points
• Output: Structured requirement spec document

Design Phase:

• Input: Requirement specs
• Processing: Generate technical design plans, including architecture diagrams, interface definitions, data models
• Output: Design spec document

Implementation Phase:

• Input: Design specs
• Processing: AI-assisted code generation, developer review and fine-tuning
• Output: Implemented code and unit tests

Verification Phase:

• Input: Implemented code + requirement specs
• Processing: Automated testing, code review, AI-assisted checks
• Output: Verification report

Each stage has clear input/output formats and conversion rules to ensure process coherence.

A common limitation of AI assistants is the context window. Project OS addresses this with a layered memory system:

Short-term Memory (Session Memory):

• Context of the current session
• Recent conversation history
• Temporary workspace state

Mid-term Memory (Project Memory):

• Project-level knowledge base
• Completed specs and decision records
• Codebase structure and key file indexes

Long-term Memory (Organization Memory):

• Cross-project best practices
• Team coding standards
• Historical project experiences and lessons learned

The memory system combines vector databases and structured storage, supporting semantic retrieval and precise queries.

Complex tasks require collaboration among multiple specialized agents. Project OS provides a sub-agent orchestration mechanism:

Role Definitions:

• Architect Agent: Responsible for high-level design and decision-making
• Developer Agent: Responsible for specific code implementation
• Tester Agent: Responsible for test case design and execution
• Reviewer Agent: Responsible for code quality and规范 checks

Collaboration Modes:

• Serial Mode: Agents execute in sequence, with the output of the previous agent as the input for the next
• Parallel Mode: Multiple agents process different subtasks simultaneously, with results aggregated
• Consultation Mode: Multiple agents jointly discuss complex issues to reach a consensus

Scheduler: The agent scheduler is responsible for task allocation and progress monitoring to ensure collaboration efficiency.