In software development, consistency is key. If three different developers work on a project without rules, the code will quickly become a mess. The same is true when working with Claude Code.

In Lesson 1, you learned WHY specifications matter for AI-assisted development. Before you write your first feature spec, you need to establish your project's foundation. A Project Constitution is a Markdown file that serves as the "source of truth" for your project. It defines the tools, the coding style, and the workflow that Claude must follow. By setting these rules at the start, you prevent Claude from making guesses about your tech stack or using outdated coding patterns. This lesson will show you how to write a constitution that ensures Claude acts like a senior engineer on your team.

CLAUDE.md is a special file that Claude Code automatically reads at the start of every session. It acts as your project's persistent memory and governance layer.

The first part of a Constitution is defining the Tech Stack. This tells Claude exactly which languages and libraries to use. We also define Architectural Principles, which act as the blueprint for how the code should be organized.

By listing specific versions (such as Python 3.11+ or PostgreSQL 15+), you ensure Claude doesn't use old features or incompatible libraries. In your CodeSignal environment, most of these tools, such as FastAPI and Pytest, are already pre-installed, so you can start using them immediately.

Next, we add the Architectural Principles:

These rules tell Claude how to write the code. For example, the Repository Pattern is a rule stating that all code dealing with the database must be kept in a specific place. This makes the code easier to test and change later.

Once the tools are chosen, we need to define the "look and feel" of the code. This is handled in the Code Standards section. These rules ensure that the code is readable and follows professional best practices.

We add this section to our Constitution:

• Type hints: These tell Python (and you) what kind of data a function expects. It's like a safety net for your code.
• Google style docstrings: These are specific ways to write comments that explain what a function does.
• Black and isort: These are tools that automatically format your code so it looks clean.

By including these in the Constitution, Claude Code will automatically follow these rules every time it generates a new file or updates an existing one.

The Workflow Rules section of your Project Constitution defines the general approach to feature development, but it's important to understand that you won't execute all steps in a single conversation.

In practice, Claude loses context in long sessions. Instead, you'll work iteratively, starting fresh conversations for each major step, always providing:

• The general context from CLAUDE.md
• The output from the previous step

The workflow section defines these key phases:

Phase 1 - Specification: Focus on WHAT the feature does (functional requirements only)

Phase 2 - Technical Design: Focus on HOW to implement (architecture, data models, APIs), referencing the specification from Phase 1

Phase 3 - Task Breakdown: Break into small tasks (max 3 files changed per task), referencing both specification and technical plan

Phase 4 - Implementation: Work task-by-task, tests first, referencing relevant spec documents for each task

Context Management: Instead of trying to maintain context across many interactions in one session, you start fresh with clear context for each phase. This prevents Claude from "forgetting" important details or making assumptions based on stale context.

Example - Moving to Phase 2:

Claude Code normally loads relevant CLAUDE.md context automatically, but you should still verify important rules and explicitly reference them when precision matters. Feature-specific documentation, like a spec or technical plan, lives outside CLAUDE.md, so you need to explicitly point Claude to the right file when you need it. You can do this in plain language:

• "Please read specs/user-auth/specification.md before we continue." - Load specific functional spec
• "Read specs/user-auth/technical-plan.md and summarize the API design." - Load technical design

You can also use the @ shorthand (for example, @specs/user-auth/specification.md) to point Claude directly at a file. Either approach lets you provide precise context for the task at hand without manual copying.

Your CLAUDE.md should contain persistent, general context that applies across all sessions:

✅ Include:

• Tech stack and versions
• Architectural principles
• Code standards and formatting rules
• General workflow phases
• Project-wide constraints and requirements

❌ Don't Include:

• Step-by-step instructions assuming continuous context
• Feature-specific details (those go in specs/)
• Temporary session state
• Long, prescriptive procedures that assume Claude "remembers" previous steps

We've now built a complete Project Constitution by combining:

• Tech Stack: The tools and versions Claude must use
• Architectural Principles: How code should be organized
• Code Standards: Professional quality requirements
• SDD Workflow Phases: The session-aware development approach

These sections together form your CLAUDE.md file. When Claude starts any session, it reads this file and understands your project's rules from the start.

Pro Tip: You can view the complete example constitution by combining all the sections we covered above. In your own projects, these four sections will form the foundation of your project governance.

Most AI-assisted development tools, including Claude Code, provide a built-in initialization command:

This command will:

• Create CLAUDE.md if it doesn't exist
• Generate a basic project constitution template
• Include common sections and best practices

You can then customize the generated file to match your project's specific needs.

If you prefer more control over the initial content, or if /init is not available, simply ask Claude to create the file with your specific requirements:

After Claude generates your CLAUDE.md, review it carefully:

Checklist:

• Tech stack matches your actual project
• Architectural principles are appropriate
• Code standards are enforceable
• Workflow phases are clear and session-aware
• No contradictions or ambiguities
• No assumptions about continuous context

You can iteratively refine the constitution by asking Claude to update specific sections:

A Project Constitution is never finished after the first draft. As you work with Claude Code across multiple features, you'll notice moments where the rules in CLAUDE.md are too vague, missing, or being interpreted inconsistently. Treat these moments as signals to evolve your constitution using a repeatable loop:

1. Observe an inconsistency: While reviewing generated code, you notice Claude solved the same type of problem two different ways in two different features (for example, one endpoint paginates results with page/limit query parameters, while another just returns the entire list).
2. Design a standard: Decide on the single approach your project should use going forward, and write it as a clear, project-wide rule rather than a one-off fix.
3. Document required and optional examples: Add the new rule to the relevant section of CLAUDE.md, including a concrete example of the required pattern and, where useful, an example of an acceptable variation versus one that is not allowed.
4. Test Claude: Start a new session, provide the updated CLAUDE.md, and ask Claude to implement or refactor a small piece of functionality that exercises the new rule. Check whether the output matches your standard.
5. Refine: If Claude's output doesn't match what you intended, the rule was probably ambiguous. Tighten the wording, add another example, or remove conflicting guidance, then test again.

This loop is exactly how experienced teams maintain their over time: they don't try to anticipate every rule up front. Instead, they let real inconsistencies in generated code drive new, specific standards. In the upcoming practices, you'll apply this loop yourself, first by adding a pagination standard, and then by documenting a standard for event publishing.

One of the upcoming practices asks you to document a standard for event publishing in CLAUDE.md. Before you get there, here's the minimum context you need:

• Event publishing means that when something important happens in your system (for example, "an order was created"), your application announces that fact as a small message, called an event, instead of, or in addition to, just updating the database.
• A publisher service is the piece of code responsible for sending that event out, typically to a message queue, a system that temporarily holds messages so other parts of the application (or even other applications) can process them later, independently, and without blocking the original request.
• Transactional integrity in this context means making sure the event is published if, and only if, the related database change actually succeeded. If your code saves a new order but crashes before publishing the "order created" event, other parts of the system will never find out about that order. Real systems solve this with dedicated patterns, but for the practice, you only need to document that your constitution requires saving and publishing to happen together, not design the underlying mechanism.

For that practice, your job is to document a supplied event-publishing pattern in CLAUDE.md, adding a tech stack entry, an architectural principle, and a required/optional example, rather than designing the queueing infrastructure yourself.

In the upcoming practice exercises, you will get hands-on experience by creating your own Project Constitution in the CodeSignal IDE. You will practice defining a tech stack and setting up workflow rules to prepare for a real-world API project!

In this lesson, we have constructed a complete Project Constitution. This document acts as a contract between you and Claude Code. By combining the Tech Stack, Architectural Principles, Code Standards, and SDD Workflow Phases, we create a comprehensive guide that ensures Claude stays on track, follows your preferred architecture, and doesn't skip important steps like testing or documentation.

The key insight: CLAUDE.md provides the general rules, but real work happens in focused sessions with explicit context.

Best Practices:

• ✅ Keep CLAUDE.md concise and general
• ✅ Start new sessions for each major phase
• ✅ Explicitly provide context from previous phases
• ✅ Use slash commands/skills when available
• ❌ Don't try to do everything in one long conversation
• ❌ Don't assume Claude remembers earlier steps without explicit context

By following this pattern, each phase is like a meeting where you review the previous work and tackle the next step with fresh focus.