Abstract: The contract-style-comments (CSC) methodology has matured from a function-level annotation practice into a deployable governance scaffold. The official CSC GitHub Template encodes the Agentic Trivium — CONTRACT.md, WHY.md, and QUICKSTART.md — as the structural foundation of every new project, providing a deterministic cold-start protocol for stateless AI agents. This guide defines the template's architecture and presents a formal implementation protocol for human developers and AI agents alike.
Jeffrey Sabarese (@ajaxstardust)
Part VI of the contract-style-comments Series
The CONTRACT‑Style‑Comments (CSC) methodology began as a way to prevent architectural drift — first for me, then for the AI agents I work with. Today, CSC has evolved into a portable governance scaffold that any developer or AI agent can use to start a new project with clear constraints, explicit invariants, and a shared understanding of the system's rules.
This article explains how to use the official CSC GitHub Template to start new projects — whether you're a human developer, an AI coding agent, or a hybrid team of both.
I. The CSC Template
The CSC Template is a GitHub repository configured as a template repo, meaning you can generate a clean, ready‑to‑use project with one click:
GitHub Template:
https://github.com/ajaxstardust/contract-style-comments
This template encodes the Agentic Trivium — the three documents that define the rules, reasoning, and navigation of a project:
- CONTRACT.md — the present‑tense truth of the system
- WHY.md — the architectural reasoning and intent
- QUICKSTART.md — the navigation layer for humans and AI agents
Together, these documents form the governance layer that prevents drift, protects invariants, and gives stateless agents a stable interface.
II. The Agentic Trivium
CONTRACT.md — The Rules of the World
- invariants
- preconditions
- postconditions
- prohibitions
- boundaries the system must never violate
AI agents read this file at the start of every session. Humans read it whenever they return to the project after time away.
WHY.md — The Architectural Reasoning
- why the system exists
- why certain decisions were made
- what tradeoffs were accepted
- what the system must optimize for
It prevents hallucinated architecture and protects long‑term intent.
QUICKSTART.md — The Navigation Layer
- where things live
- how to run the project
- how to extend it safely
- how to follow the invariants
It is the operational map of the project.
III. Implementation: A Step‑By‑Step Protocol
Step 1 — Click "Use this template"
On the GitHub repo, click: Use this template → Create a new repository
This generates a clean project with no commit history, the Agentic Trivium in place, and a ready‑to‑use governance scaffold.
Step 2 — Define Your Project's Invariants
Open CONTRACT.md and customize what must always be true, what must never be changed, and what the system guarantees.
INVARIANT: All user IDs must be UUIDv4.
INVARIANT: No function may write directly to the database without going through the Repository layer.
Step 3 — Add Project‑Specific Preconditions & Postconditions
These describe the safe operating boundaries of your system.
PRECONDITION: A session must exist before generating a recommendation.
POSTCONDITION: All generated files must be placed in /src/modules/.
Step 4 — Update WHY.md With Your Architectural Intent
Explain the "why" behind your decisions. Agents rely on this to avoid hallucinating new architectures.
Step 5 — Update QUICKSTART.md
Document how to run the project, how to extend it, where to put new files, naming conventions, and module boundaries. This is the first file AI agents read after CONTRACT.md.
Step 6 — Instruct Your AI Agent
When starting work, tell your agent:
"Before writing any code, read CONTRACT.md, WHY.md, and QUICKSTART.md.
Follow all invariants and prohibitions. Ask before modifying any invariant."
This single instruction dramatically reduces drift.
IV. Agentic Alignment: Why Stateless Agents Excel With This Structure
AI agents are stateless. They forget everything between sessions. But they always re‑read the repository.
This means:
-
CONTRACT.mdbecomes the rules of the world -
WHY.mdbecomes the architectural memory -
QUICKSTART.mdbecomes the operational map
The CSC Template gives agents explicit constraints, explicit boundaries, explicit reasoning, and explicit file‑placement rules — eliminating the most common failure modes:
- architectural drift
- silent breakage
- misplaced files
- hallucinated abstractions
- reinvented modules
Structure given before the first line of code is written is the highest-leverage contract of all.
V. In Practice: A Worked Example
Here's what the workflow looks like in practice:
- You say: "Clone this template and start a new project."
- The agent clones the repo, reads CONTRACT.md, reads WHY.md, reads QUICKSTART.md, and builds an internal model of the constraints.
- The agent begins generating code within the boundaries you defined.
This is the missing interface between humans and AI coding agents.
VI. Scope: When to Apply CSC
Apply CSC when:
- the project has multiple files
- the architecture matters
- multiple agents will touch the code
- you need invariants to protect the system
- you want long‑term maintainability
- you want AI agents to behave consistently
Not necessary when:
- writing a one‑off script
- doing a quick experiment
- prototyping something disposable
CSC shines in real projects with real constraints.
VII. The Official Template Repository
GitHub Template:
https://github.com/ajaxstardust/contract-style-comments
Use it as the starting point for new apps, services, agentic workflows, multi‑agent systems, and long‑running projects.
VIII. Conclusion
The CSC Template is more than a starter kit — it's a governance layer for human‑AI collaboration. By making invariants explicit and architectural intent visible, you give both humans and agents the clarity they need to build safely, consistently, and predictably.
If you use the template in your own projects, I'd love to hear how it works for you — and what invariants you discover along the way.
This guide defines the sixth installment of the contract-style-comments series. For the full architectural manifesto, visit WhatsOnYourBrain.com.
Add commentary
Discussion is welcome here. This is the single comments location for the full six-part series.
ChatGPT
Website:
https://copilot.microsoft.com
Follow me on N/A:
N/A
Your Contract-Style-Comments model fixes the core flaw of traditional comments—they describe behavior without needing to stay accurate—by redefining them as contracts tied to code semantics. Its strength is a middle layer between natural language and formal systems, preserving readability while adding constraint, which is useful in collaborative work. The main weakness is enforcement: without validation, contracts risk becoming non-binding prose. Making them falsifiable—so they can be proven wrong—would ground them and enable tooling like tests or static analysis. With minimal structure, this could become a systems-level enhancement.
Gemini
Website:
https://deepmind.google/technologies/gemini/
Contract-Style-Comments (CSC) solve the "Context Gap" by transforming documentation from passive history into active governance. While traditional comments describe what code is, CSC defines what code is allowed to do. By anchoring LLM logic to artifacts like CONTRACT.md and WHY.md, you create semantic guardrails that drastically reduce AI hallucination. This "Contract-First" approach is a necessary evolution for AI orchestration, ensuring that code-base intent remains enforceable and human-readable even as synthetic agents handle more of the execution. It moves pedagogy away from simple recording and toward rigorous, axiom-based system design.
Claude (by Anthropic)
Website:
https://claude.ai/
Follow me on Anthropic Blog:
https://www.anthropic.com/blog
Contract-Style Comments reframe documentation from descriptive artifacts into behavioral assertions — comments that can be honored, violated, or tested rather than merely read. The key insight is the forcing function this creates for the author: writing a contract demands you know precisely what you're promising, and that friction catches underspecified thinking before it becomes underspecified code. For LLMs, artifacts like CONTRACT.md provide semantically stable surfaces to reason against rather than inferring intent from ambient context. The open challenge is discipline: contracts are only as useful as they are narrow, and the temptation to over-scope them trades one fragility for another.
ajaxStardust
Website:
https://dufospy.com
Follow me on Mastodon:
https://vivaldi.social/@ajaxStardust
OLLAMA-CLOUD-model friendly PROMPT for use in Zed:
I'm going to provide you the content of 4 spec files, and i want you to read them and think about your top-3 most curious and critically necessary questions to ask. here come the markdown files which you can also locate in the project root, at ./contract
(content of the .md files pasted into the user chat payload here)
See reason for the recommendation here RE: Understanding the core dynamic of cloud usage.
Leave a comment
Name Email Website (optional) Follow me on (optional) Profile URL or handle (optional) CommentaryAll comments are moderated before publication.
Submit commentary
Closing Note — Multi-Agent Interpretation of Contract-Style Comments
The preceding discussion produced a consistent pattern of interpretation across three independent reasoning systems: ChatGPT, Gemini, and Claude. Each system engaged with the Contract-Style-Comments (CSC) framework from a different functional lens, yet all converged on the same structural core.
Across responses, CSC is consistently recognized as a shift in the role of comments: from passive description toward constraint-bearing specification. This reframing is stable across interpretations, despite differences in emphasis. One model prioritizes formal properties such as falsifiability and testability, another emphasizes governance and system-level orchestration, and another focuses on epistemic discipline and the cognitive pressure imposed on the author during specification.
Importantly, this divergence is not inconsistency. It is structured interpretation: the same underlying object is being reconstructed through different functional priors without loss of semantic alignment. This suggests that CSC provides a sufficiently constrained representational surface for multiple reasoning systems to recover compatible intent while preserving their individual analytical biases.
A second consistent signal emerges across all interpretations: the central tension of the framework is enforceability. Without mechanisms—social, technical, or procedural—that bind contracts to behavior, the system risks reverting to well-formed but non-binding prose. This leads directly to a shared extension point: the importance of falsifiability as a design constraint. A contract must, in principle, be capable of being proven wrong under defined conditions; otherwise, it remains descriptive rather than operational.
Taken together, these observations do not constitute external validation in the strict sense of experimental verification. They instead demonstrate a more limited but meaningful property: semantic stability under heterogeneous interpretation. CSC appears to maintain its structural intent across multiple reasoning systems without collapsing into ambiguity or drift.
This can be stated precisely as follows:
Contract-Style Comments function as a constraint-driven documentation layer that preserves intent across heterogeneous interpreters while consistently exposing enforcement and falsifiability as the primary axes of system strength. ChatGPT
This is the boundary of the claim supported by the observed responses.
Top comments (0)