Project Constitution Introduction

Introduction to the Project Constitution

In software development, consistency is key. When three developers work on a project without shared rules, the codebase quickly becomes fragmented and unmaintainable. The same principle applies when working with Codex. Without clear guidelines, the AI will make arbitrary decisions about architecture, coding style, and implementation patterns. A project constitution is a Markdown file that serves as the source of truth for your entire project. It defines the tools, coding standards, architectural patterns, and development workflow that Codex must follow. This document ensures Codex behaves like a disciplined senior engineer rather than making guesses about your tech stack or using outdated patterns. By establishing these rules upfront, you create a foundation for consistent, high-quality code generation across all sessions.

Understanding CODEX.md

The file CODEX.md acts as your project's persistent memory and governance layer. Codex automatically reads this file at the start of every session, making it the perfect place to define rules that should apply universally across your entire project. Unlike feature-specific documentation that changes frequently, your constitution contains the stable, foundational decisions that remain consistent throughout development. Think of CODEX.md as a contract between you and the AI. When you start a new session, Codex immediately loads this file and uses it to guide every decision it makes. This automatic loading mechanism means you never have to manually remind Codex about your project's standards, they are always present from the first moment of any interaction.

Defining Your Tech Stack

The first section of your constitution specifies the exact tools and versions that Codex must use. This prevents the AI from making assumptions or using outdated libraries. Here is how you define a tech stack for a task management API: Markdown # Project Constitution: TaskMaster API ## Tech Stack (Non-Negotiable) - Python 3.11+ with type hints (mypy strict mode) - FastAPI 0.100+ (latest stable) - Pytest with >90% coverage requirement - PostgreSQL 15+ (primary data store) - Redis 7+ (caching, pub/sub) Notice how each tool includes specific version constraints. Specifying Python 3.11+ rather than just "Python" ensures Codex uses modern features and avoids deprecated patterns. The term "non-negotiable" signals to Codex that these choices are final decisions, not suggestions. In your CodeSignal environment, tools like FastAPI and Pytest come pre-installed, allowing you to start development immediately. After listing the tools, you define architectural principles that govern how code should be structured: Markdown ## Architectural Principles 1. Repository Pattern: All database access through repositories 2. Dependency Injection: Use constructor injection for services 3. API-First: API schema drives implementation 4. Stateless: No session state on server ## Architectural Principles 1. Repository Pattern: All database access through repositories 2. Dependency Injection: Use constructor injection for services 3. API-First: API schema drives implementation 4. Stateless: No session state on server These principles act as architectural guardrails. The repository pattern, for example, requires all database interactions to happen through dedicated repository classes rather than scattered throughout the codebase. This separation makes code easier to test and modify. Dependency injection ensures services remain loosely coupled and testable. Together, these rules create a consistent architecture that Codex will follow in every feature it generates.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Markdown

## Architectural Principles
1. Repository Pattern: All database access through repositories
2. Dependency Injection: Use constructor injection for services
3. API-First: API schema drives implementation
4. Stateless: No session state on server

Markdown

## Code Standards
- Python type hints required for all functions (mypy strict mode)
- Docstrings for all public APIs (Google style)
- Error handling: Custom exception classes, never silent except blocks
- Formatting: Black (default settings), Ruff for linting

## Code Standards
- Python type hints required for all functions (mypy strict mode)
- Docstrings for all public APIs (Google style)
- Error handling: Custom exception classes, never silent except blocks
- Formatting: Black (default settings), Ruff for linting

Markdown

## SDD Workflow

Phase 1 - Specification: Define what the feature does (functional requirements only)
Phase 2 - Technical Design: Define how to implement it (architecture, data models, APIs)
Phase 3 - Task Breakdown: Split work into small tasks (max 3 files per task)
Phase 4 - Implementation: Work task by task, write tests first

## SDD Workflow

Phase 1 - Specification: Define what the feature does (functional requirements only)
Phase 2 - Technical Design: Define how to implement it (architecture, data models, APIs)
Phase 3 - Task Breakdown: Split work into small tasks (max 3 files per task)
Phase 4 - Implementation: Work task by task, write tests first

text

I need to create the technical plan for the user authentication feature.

CONTEXT FROM CODEX.MD:
[paste relevant sections from CODEX.md]

SPECIFICATION (from Phase 1):
[paste or attach specs/user-auth/specification.md]

Create specs/user-auth/technical-plan.md following our technical design standards.

I need to create the technical plan for the user authentication feature.

CONTEXT FROM CODEX.MD:
[paste relevant sections from CODEX.md]

SPECIFICATION (from Phase 1):
[paste or attach specs/user-auth/specification.md]

Create specs/user-auth/technical-plan.md following our technical design standards.

Document	When The Agent Reads
API Schema	Every API change
`CODEX.md`	Start of every session
Code + Tests	When modifying features

text

Create CODEX.md for the TaskMaster project with the following details:

PROJECT SUMMARY:
- A task management API for personal productivity
- Users create tasks with priorities, due dates, and tags
- RESTful API with JWT authentication

TECH DECISIONS:
- Python 3.11+ with type hints (chosen for type safety and modern async support)
- FastAPI (need high performance and built-in schema validation with Pydantic)
- PostgreSQL with asyncpg driver (need relational data with transactions)
- JWT auth (stateless, scalable)

TEAM STANDARDS:
- Follow PEP 8 style guide
- Minimum 90% test coverage with Pytest
- All business logic must be testable without HTTP layer
- Error messages must be user-friendly (no technical jargon)
- Mypy strict mode enabled

CONSTRAINTS:
- No external service dependencies (runs fully local)
- Maximum response time: 200ms for simple queries
- Database migrations use Alembic

WORKFLOW:
- Multi-session approach: each major phase in a separate conversation
- Always reference CODEX.md and previous phase outputs

Create CODEX.md for the TaskMaster project with the following details:

PROJECT SUMMARY:
- A task management API for personal productivity
- Users create tasks with priorities, due dates, and tags
- RESTful API with JWT authentication

TECH DECISIONS:
- Python 3.11+ with type hints (chosen for type safety and modern async support)
- FastAPI (need high performance and built-in schema validation with Pydantic)
- PostgreSQL with asyncpg driver (need relational data with transactions)
- JWT auth (stateless, scalable)

TEAM STANDARDS:
- Follow PEP 8 style guide
- Minimum 90% test coverage with Pytest
- All business logic must be testable without HTTP layer
- Error messages must be user-friendly (no technical jargon)
- Mypy strict mode enabled

CONSTRAINTS:
- No external service dependencies (runs fully local)
- Maximum response time: 200ms for simple queries
- Database migrations use Alembic

WORKFLOW:
- Multi-session approach: each major phase in a separate conversation
- Always reference CODEX.md and previous phase outputs

text

Update the Code Standards section to include:
- Ruff configuration for linting with default rules
- Black with default settings for formatting
- Pytest for unit tests with minimum 90% coverage
- Pre-commit hooks for linting and testing

Update the Code Standards section to include:
- Ruff configuration for linting with default rules
- Black with default settings for formatting
- Pytest for unit tests with minimum 90% coverage
- Pre-commit hooks for linting and testing

Markdown

## Code Standards
- Python type hints required for all functions (mypy strict mode)
- Docstrings for all public APIs (Google style)
- Error handling: Custom exception classes, never silent except blocks
- Formatting: Black (default settings), Ruff for linting

Markdown

## SDD Workflow

Phase 1 - Specification: Define what the feature does (functional requirements only)
Phase 2 - Technical Design: Define how to implement it (architecture, data models, APIs)
Phase 3 - Task Breakdown: Split work into small tasks (max 3 files per task)
Phase 4 - Implementation: Work task by task, write tests first

text

I need to create the technical plan for the user authentication feature.

CONTEXT FROM CODEX.MD:
[paste relevant sections from CODEX.md]

SPECIFICATION (from Phase 1):
[paste or attach specs/user-auth/specification.md]

Create specs/user-auth/technical-plan.md following our technical design standards.

text

Create CODEX.md for the TaskMaster project with the following details:

PROJECT SUMMARY:
- A task management API for personal productivity
- Users create tasks with priorities, due dates, and tags
- RESTful API with JWT authentication

TECH DECISIONS:
- Python 3.11+ with type hints (chosen for type safety and modern async support)
- FastAPI (need high performance and built-in schema validation with Pydantic)
- PostgreSQL with asyncpg driver (need relational data with transactions)
- JWT auth (stateless, scalable)

TEAM STANDARDS:
- Follow PEP 8 style guide
- Minimum 90% test coverage with Pytest
- All business logic must be testable without HTTP layer
- Error messages must be user-friendly (no technical jargon)
- Mypy strict mode enabled

CONSTRAINTS:
- No external service dependencies (runs fully local)
- Maximum response time: 200ms for simple queries
- Database migrations use Alembic

WORKFLOW:
- Multi-session approach: each major phase in a separate conversation
- Always reference CODEX.md and previous phase outputs

text

Update the Code Standards section to include:
- Ruff configuration for linting with default rules
- Black with default settings for formatting
- Pytest for unit tests with minimum 90% coverage
- Pre-commit hooks for linting and testing

Introduction to the Project Constitution

Understanding CODEX.md

Defining Your Tech Stack

Join the 1M+ learners on CodeSignal

Code Standards And Quality

Workflow Phases

Context Management Strategy

Loading Feature Documentation

Constitution Content Guide

Creating Your Constitution

Refining Your Setup

Summary