DocOps

Stop losing context. Start coding with confidence.

The Problem: Vibe Coding Without a Map

You're using AI to write code. It's fast. It's magical. It's also slowly eroding your understanding of your own codebase.

Every time you prompt "add a payment feature" or "fix the authentication", the AI generates code. You accept it. It works. But:

• You don't fully understand what it did
• You forget how components connect
• The codebase grows, but your mental model doesn't
• Context window limits mean the AI forgets too

After a few weeks:

• You need to change the order flow but can't remember which services are involved
• The AI suggests changes that break hidden dependencies
• You're debugging code you don't recognize
• Documentation? Outdated five commits ago

The paradox: The more AI helps you code, the less you understand your code.

---

The Solution: Contracts as Source of Truth

DocOps creates contracts — structured documentation files that describe every source file in terms of:

| Section | Purpose | |---------|---------| | DEPENDS ON | What this file uses | | USED BY | What uses this file | | EXPECTS | Requirements for inputs | | GUARANTEES | What it promises to deliver | | FORBIDDEN | What it must NEVER do |

These contracts are:

• AI-generated from your source code
• Human-readable for understanding
• Machine-parseable for AI agents to follow
• Automatically aggregated into system-level documentation

The Philosophy: Shared Responsibility

DocOps is not about AI doing all the work or humans writing all the docs.

It's a collaboration:

| Actor | Role | |-------|------| | AI | Generates initial contract structure, suggests updates, fills in technical details | | Human | Reviews, corrects, adds context, defines constraints and FORBIDDEN rules |

The maintenance of documentation is a shared responsibility:

• AI can create the initial structure and suggest details based on code analysis
• Human can do the same, but also direct the AI's behavior by editing contracts

When you edit a contract:

• You're teaching the AI what matters
• You're constraining future changes to respect your design
• You're documenting intent that code alone can't express
• You're directing future AI actions by defining boundaries and rules

The human shapes the boundaries. The AI fills in the details. Both can initiate, both can refine.

---

How It Works

# Initialize in your project
docops init

# Generate contracts for all files
docops sync

This creates:

docs/
├── contracts/              # One .contract.md per source file
│   └── src/
│       └── services/
│           └── order_service.contract.md
├── spec/
│   ├── domains.md          # Bounded contexts (auto-generated)
│   └── principles.md       # System laws from FORBIDDEN sections
└── dependencies.md         # Mermaid graph of relationships

---

Installation

pip install docops

Or from source:

git clone https://github.com/ferdinandobons/DocOps.git
cd DocOps
pip install -e .

---

Configuration

DocOps supports 100+ LLM providers via LiteLLM. Configure in .env:

Anthropic (Default)

DOCOPS_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_API_KEY=sk-ant-...

OpenAI

DOCOPS_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

Google Gemini

DOCOPS_MODEL=gemini/gemini-pro
GEMINI_API_KEY=...

Ollama (Free, Local)

DOCOPS_MODEL=ollama/llama3
# No API key needed - runs locally

Azure OpenAI

DOCOPS_MODEL=azure/gpt-4
AZURE_API_KEY=...
AZURE_API_BASE=https://your-resource.openai.azure.com

Other Providers

| Provider | Model Format | API Key Env Var | |----------|--------------|-----------------| | Mistral | mistral/mistral-large | MISTRAL_API_KEY | | Groq | groq/llama-70b | GROQ_API_KEY | | AWS Bedrock | bedrock/anthropic.claude-v2 | AWS credentials | | Together AI | together_ai/meta-llama/Llama-3-70b | TOGETHER_API_KEY |

See LiteLLM docs for all supported providers.

---

Commands

docops init          # Initialize DocOps structure
docops sync          # Sync contracts for the entire project
docops ai            # Show AI agent guidance
docops version       # Show version

Targeted Sync

docops sync accepts files and/or directories to sync only specific targets:

docops sync main.py                        # single file
docops sync src/services/                  # entire directory
docops sync main.py src/utils/ lib.py      # mix files and dirs

Options

| Flag | Effect | |------|--------| | --force | Regenerate contracts even if they already exist | | --dry-run | Preview what would be generated, without writing files |

docops sync --force                  # regenerate everything
docops sync main.py --force          # regenerate one file
docops sync --dry-run                # preview only

---

For AI Agents

DocOps is designed to work with AI coding assistants. Include this in your AI agent configuration:

Supported Tools

| Tool | Config File | |------|-------------| | Cursor | .cursorrules | | Windsurf | .windsurfrules | | Cline | .clinerules | | Claude Code | CLAUDE.md | | Continue.dev | .continue/config.json | | Aider | .aider.conf.yml |

Add this to your config file:

## DocOps Integration

This project uses DocOps for normative documentation.

- Run `docops --help` and `docops sync --help` to see available commands and options.
- Run `docops ai` to see the full contract structure, workflow, and constraints.

### Before Making Changes
1. Read `docs/dependencies.md` to understand file relationships
2. Read the contract for any file you plan to modify: `docs/contracts/{path}/{filename}.contract.md`
3. Check FORBIDDEN section to avoid violations
4. Check DEPENDS ON and USED BY to understand impact

### After Making Changes
1. If you modified a file's behavior, update its contract
2. If you added new files, create contracts for them
3. Run `docops sync` to regenerate aggregated docs
4. Verify your changes don't violate any FORBIDDEN rules

### Key Principle
**Contracts are the Source of Truth.** When code and contract disagree, fix the code.

---

Why This Works

1. Contracts survive refactoring — Even when code changes, the contracts document intent
2. AI stays aligned — Agents can read contracts before modifying files
3. Context is preserved — DEPENDS ON/USED BY create an explicit dependency graph
4. Constraints are enforced — FORBIDDEN sections prevent common mistakes
5. Understanding scales — System-level docs aggregate from file-level contracts

---

The DocOps Philosophy

Code changes. Context fades. Contracts persist.

• Don't trust memory — Document everything
• Don't trust AI alone — Contracts constrain it
• Don't trust outdated docs — Regenerate from source
• Don't trust implicit knowledge — Make dependencies explicit

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check docops tests

# Run type checking
mypy docops

---

License

MIT