Turning Our R&D Guidelines into a Versioned Git Repository

Why traditional guidelines fail

Documentation in a static Wiki quickly becomes outdated as code changes.

Team members rarely read the Wiki; new hires rely on asking seniors.

Compliance depends on self‑discipline without enforcement.

Traditional "archive‑style" guidelines sit idle until someone reads them, by which time the code may have already diverged.

Meta‑repository for team configuration

The team stores all development conventions in a "workspace meta‑repo" that contains only configuration, not business code. Repository layout:

team-workspace/  # Meta‑repo: versioned team shared configuration
├── CLAUDE.md               # Cross‑project overview and collaboration conventions (read by Claude)
├── .claude/
│   ├── agents/            # Six virtual roles
│   ├── skills/            # Team skills
│   ├── workflows/         # Development pipelines
│   ├── rules/             # General rules
│   └── settings.json      # Unified plugin switches
└── .mcp.json              # Team‑wide MCP tool configuration

Design choice 1: a whitelist .gitignore that ignores everything by default and only allows explicit configuration files, preventing accidental inclusion of business code or secrets.

Design choice 2: business code lives in separate Git repositories; the meta‑repo does not lock versions or use submodules, keeping configuration and code fully decoupled.

Benefit: new members clone the meta‑repo and instantly inherit the full set of roles, skills, and tools, achieving zero‑configuration onboarding.

Real‑world case: on a new hire's first day, cloning the meta‑repo and running a script to sync sub‑projects reduced environment setup from half a day to a few minutes.

Security note: access tokens are stored in a locally ignored file and never committed, so configuration is shared while credentials remain private.

Six AI roles

Product Architect (Planning layer) – responsible for requirement breakdown, architecture decisions, cross‑platform contracts, UI/UX design.

Backend Engineer (Development layer) – owns backend APIs, data models, permission logic, AI orchestration.

Frontend Engineer (Development layer) – manages admin pages, routing, and chart components.

Mini‑Program Engineer (Development layer) – handles multi‑platform mini‑programs, streaming chat, and state management.

Quality Engineer (Quality layer) – conducts code review, testing, and enforces security redlines.

Ops Engineer (Operations layer) – oversees build & deployment, containers, gateways, and credential management.

Each role file binds the role to a concrete tech stack, directory boundaries, and red‑line rules. For example, the backend role encodes the project's pagination implementation, automatic timestamp handling, and mandatory log suppression; the mini‑program role enforces a unified network request wrapper and streaming response handling.

The team originally defined seven roles but merged the designer into the product architect after observing that design and architecture were inseparable in practice, arriving at six roles that match actual collaboration patterns.

Task routing

Two core routing rules are defined in CLAUDE.md:

Path‑based ownership: a task that touches a specific project directory is assigned to the corresponding role.

Intent routing: when no clear file is involved, the task’s intent determines the role (e.g., “optimize AI dialogue” → backend, “design new page interaction” → product architect).

Additional rules ensure deterministic behavior:

Path priority: if a task maps to a sub‑project directory, path‑based routing wins; intent routing is used only when no explicit file is identified.

Cross‑platform changes first pass through the architect: any modification that may affect interface contracts or error codes is routed to the product architect to define the contract before distribution.

Parallel delegation: independent sub‑tasks (e.g., adding a backend API and implementing the corresponding front‑end page) are dispatched concurrently rather than serially.

Examples: “Add a pagination API” is automatically routed to the backend engineer; “integrate real‑time messages in the mini‑program” routes the mini‑program role as lead with backend support; “evaluate impact of a field change” first goes to the product architect to define contracts.

Unified tools: MCP and skills

The meta‑repo version‑controls the MCP tool and skill definitions.

MCP integrates external data sources and systems, providing two capabilities:

Latest documentation lookup: before answering any library or SDK question, the AI fetches the official latest docs, avoiding outdated knowledge.

DevOps integration: connects tickets, codebases, and pipelines so the AI can read/write without manual copy‑paste.

Skills trigger automatic actions, such as:

Posting a defect ticket number initiates a full “fetch ticket → locate root cause → fix → build verification → update ticket status → comment → submit” loop.

Asking how to use a third‑party library automatically pulls its latest official documentation.

Because tools are versioned alongside roles, every teammate opens the project with the same toolset, eliminating “missing tool” issues.

End‑to‑end workflow pipeline

The full requirement flows through a four‑stage pipeline:

Planning + contract: product architect produces specs, acceptance criteria, and cross‑platform contracts.

Design: UI/UX proposals (skipped for pure backend tasks).

Development (parallel): engineers on each platform implement solutions concurrently.

Quality gate: quality engineer verifies each acceptance criterion, checks security redlines, and issues pass/fail/return.

Each stage outputs structured deliverables in a fixed format, not free‑form chat, facilitating smooth hand‑offs and rapid human review.

The pipeline deliberately produces only reviewable proposals; the AI does not modify code until humans approve the plan, preventing fast but misdirected code generation.

A common pitfall is that roles lack shared context, so tasks would not automatically hand off. The central agent’s routing table handles dispatch, but full end‑to‑end automation requires the workflow orchestration.

Why this approach makes guidelines stick

Guidelines become configuration, not passive docs: redlines live in CLAUDE.md and are read automatically by the AI on every task.

Zero‑config onboarding: cloning the meta‑repo gives every new member the complete set of roles, skills, and tools, ensuring a completely consistent environment.

Team‑wide sync on every change: updating the Git‑tracked configuration propagates instantly to all members.

Clear routing rules: responsibilities are enforced by mandatory rules rather than informal conventions.

Thus the R&D guideline evolves from a bulky Wiki into executable configuration that the AI consumes on each operation, closing the gap between AI‑native and traditional teams in achieving guideline compliance.