Engineering Standards as Code

A working starter kit for running engineering teams across multiple offices, time zones, or countries — with the same standards, the same workflows, and far fewer status meetings.

If your engineers are spread across more than one location, this repo gives you a ready-to-use scaffold that turns your engineering standards, sprint workflows, and status reporting into files that live in your codebase. Every engineer on every site gets the same starting point automatically.

Companion to the LinkedIn article: Distributed Engineering Runs on Repo Files. Or It Drifts. Last validated: April 2026, against Claude Code stable.

---

Who is this for?

You will get value from this repo if:

• You lead an engineering team that operates from more than one location.
• You are tired of repeating the same standards in code reviews, onboardings, and Slack threads.
• You want your daily standups replaced by something less manual and more honest.
• You use, or are starting to use, Claude Code as your AI coding assistant.

You do not need to be a Claude Code expert. The files in this repo are commented and editable. If you can edit a JSON file and a markdown file, you can use this scaffold.

---

What this actually does, in plain English

Imagine three things every distributed engineering team complains about:

1. "Each office writes code a little differently." — Drift.
2. "Decisions made in one time zone reach the next site too late." — Delay.
3. "By the time I hear about a problem in standup, it is already a real problem." — Distortion.

This repo addresses all three by moving the answers into the codebase itself:

• A CLAUDE.md file at the root tells every engineer's AI tool what "good code" looks like for your team. New hires read the same standards as senior engineers, automatically, on day one.
• Skills in .claude/skills/ are reusable workflows. Anyone can run /pr-review, /sprint-plan, or /weekly-status and get the same structured output, regardless of which office they sit in.
• Hooks in .claude/hooks/ are small scripts that run automatically. They block commits without ticket references and pushes that break your API contract — before a human ever sees the PR.
• .mcp.json connects your AI tool to Jira, GitHub, and your CI system. That is what lets /weekly-status produce a real-time, computed status report instead of asking humans to type one up.

Everything is plain text. Everything is version-controlled. Everything is the same on every machine on every site.

---

What is in this repo

engineering-standards-as-code/
├── README.md                     ← You are here
├── LICENSE                       ← MIT license
├── CLAUDE.md                     ← Your team's "five non-negotiables"
├── .mcp.json                     ← Connections to Jira, GitHub, CI
├── .gitignore                    ← Standard ignores + per-engineer overrides
└── .claude/
    ├── settings.json             ← Wires up the hooks
    ├── skills/                   ← Reusable AI workflows (slash commands)
    │   ├── pr-review.md          ← /pr-review — pre-review PR pass
    │   ├── sprint-plan.md        ← /sprint-plan — turn PRD into issues
    │   └── weekly-status.md      ← /weekly-status — computed status report
    └── hooks/                    ← Automated policy enforcement
        ├── check-jira-ref.sh     ← Blocks commits without a ticket ID
        └── validate-openapi.sh   ← Blocks pushes that break the API contract

File-by-file explanation

CLAUDE.md — Read first. This is the single page every engineer's AI tool reads at session start. It defines the team's API conventions, entity model rules, data contract policy, test bar, and PR review checklist. Keep it short. Treat it like a one-page constitution for the codebase.

.mcp.json — Tells Claude Code which external systems it can talk to. Templates included for Atlassian (Jira), GitHub, and a generic CI server. Replace the placeholder URLs and set the environment variables on each engineer's machine. The connections themselves are committed; only the secrets are local.

.claude/settings.json — Wires the hooks below into Claude Code's lifecycle events. You can ignore this file once it's set up.

.claude/skills/pr-review.md — When an engineer types /pr-review, Claude Code runs a structured pre-review pass: checks API conventions, entity model usage, contract changes, test coverage. The output is a Blockers / Warnings / Clean report. This catches the obvious style violations before a human reviewer sees them.

.claude/skills/sprint-plan.md — When a leader or engineer types /sprint-plan and pastes in a PRD, the skill produces a YAML list of scoped issues with explicit cross-team dependencies. Useful when you want sprint planning to be a 30-minute repo activity instead of a 2-hour meeting.

.claude/skills/weekly-status.md — When anyone types /weekly-status, the skill calls Jira (via MCP), GitHub (via MCP), and your CI system to compute a real status report: sprint health, PR flow, CI health, and a list of exceptions worth discussing. This is the file that lets you replace standups with a query.

.claude/hooks/check-jira-ref.sh — Runs automatically before any git commit. If the commit message does not reference a ticket like PROJ-1234, the commit is blocked. Override is available with an env var, but the default is enforcement. Edit the TICKET_PREFIX at the top to match your scheme.

.claude/hooks/validate-openapi.sh — Runs automatically before any git push. If your openapi.yaml has a breaking change versus main, the push is blocked. Requires the oasdiff tool installed; if it is not, the hook warns and continues, so you are never accidentally blocked by missing tooling.

LICENSE — MIT. Use it however you want. Attribution is appreciated but not required.

---

Quickstart: 10 minutes to a working setup

Prerequisites

• Claude Code installed on every engineer's machine.
• Access to your team's Jira workspace, GitHub org, and CI system.
• Optional: oasdiff installed if you maintain an OpenAPI spec and want push-time contract checks.

Step 1: Get the files into your repo

Two options:

Option A — Clone this repo as a starting point:

git clone https://github.com/iammanoj/engineering-standards-as-code.git my-team-standards
cd my-team-standards

Option B — Copy the files into your existing project:

# From the root of your existing project:
curl -L https://github.com/iammanoj/engineering-standards-as-code/archive/refs/heads/main.tar.gz \
  | tar -xz --strip=1 distributed-engineering-stack-main

Step 2: Customize the placeholders

Open these files and replace the YOUR-* placeholders with your real values:

• CLAUDE.md — Adjust the five non-negotiables to match your team's actual conventions. Some teams use camelCase JSON, some use offset pagination, some have different versioning rules. Make this file true for your team.
• .mcp.json — Replace YOUR-WORKSPACE, YOUR-ORG, and the CI URL.
• .claude/hooks/check-jira-ref.sh — At the top, change TICKET_PREFIX="PROJ" to your actual prefix (e.g., ENG, PLAT, INFRA).
• .claude/hooks/validate-openapi.sh — If your OpenAPI spec lives somewhere other than ./openapi.yaml, set OPENAPI_PATH.

Step 3: Set environment variables on each engineer's machine

Each engineer creates a .env file (or sets these in their shell profile). These are not committed.

export ATLASSIAN_API_TOKEN="..."        # https://id.atlassian.com/manage-profile/security/api-tokens
export ATLASSIAN_USER_EMAIL="..."
export GITHUB_PERSONAL_ACCESS_TOKEN="..." # https://github.com/settings/tokens
export CI_API_TOKEN="..."

Step 4: Make the hooks executable

chmod +x .claude/hooks/*.sh

Step 5: Open the project in Claude Code

cd my-team-standards
claude

Claude Code will automatically pick up CLAUDE.md, the skills in .claude/skills/, the hooks via .claude/settings.json, and the MCP connections from .mcp.json.

Step 6: Try a slash command

Inside Claude Code, type:

/weekly-status

If your MCP servers are connected and the env vars are set, you should see a computed status report within a minute. That is the Mirror Layer working.

---

Customization checklist

Before rolling this out to your team, walk through this list:

• CLAUDE.md: API conventions match your team's actual style (casing, pagination, versioning, errors).
• CLAUDE.md: Test bar percentage matches your real coverage gate.
• CLAUDE.md: PR review checklist matches your team's review etiquette.
• .mcp.json: Workspace URLs and org names replaced.
• .mcp.json: CI server entry replaced with your actual CI provider's MCP server, or removed if not yet supported.
• check-jira-ref.sh: Ticket prefix matches your scheme.
• validate-openapi.sh: Spec path matches your repo layout (or skip this hook if you do not maintain an OpenAPI contract).
• Skills: Add or remove .claude/skills/*.md files based on the workflows your team actually repeats.
• Onboarding: One paragraph in your team's onboarding doc that says "clone the repo, set these env vars, type /weekly-status to verify."

---

Frequently asked questions

Q: Do I need to be on the latest Claude Code version? Anything from the public stable channel of Claude Code in 2025 onward should work. If a feature in this scaffold is not recognized, run claude --version and update.

Q: My team uses a different ticket system (Linear, Shortcut, etc.). Will this work? Yes. Replace @atlassian/mcp-server-atlassian in .mcp.json with the MCP server for your tool, and update check-jira-ref.sh to match the ID format your tool uses (e.g., LIN-1234, sc-1234).

Q: We do not use Jira at all. Can I still use the rest? Yes. Remove the atlassian block from .mcp.json and the ticket-reference hook. The PR review skill, OpenAPI hook, and standards file are all useful on their own.

Q: Will the hooks block my CI/CD pipeline? The hooks here run inside Claude Code only, not in your CI. They prevent an engineer from making a bad commit through Claude Code, but they do not run on a push from another tool. If you want server-side enforcement, add the same checks to your CI workflows.

Q: Can I commit my secrets to .mcp.json? Do not. The template uses environment variable references (${ATLASSIAN_API_TOKEN}) so the file is safe to commit. The actual tokens stay on each engineer's machine.

Q: What if my team only has one office? The scaffold still works. You will get most of the value from the standards file and the PR review skill, with less benefit from the cross-time-zone framing. The /weekly-status skill is still useful for replacing manual status meetings.

---

Contributing

This is a reference scaffold, kept minimal on purpose. Pull requests are welcome if they:

• Fix a bug or a typo.
• Update for a new Claude Code version.
• Simplify something that has accidentally become complex.

PRs that add new skills, new hooks, or new layers will be politely declined unless they replace something else. The point of this repo is what it does not contain.

---

License

MIT. Full text in LICENSE. Attribution to this repo is appreciated but not required.

---

Credits

Originally published alongside the article Distributed Engineering Runs on Repo Files. Or It Drifts. by Manoj Mohan on LinkedIn. If this repo helps your team, let me know — feedback shapes the next revision.