Rethinking Jira, Confluence, and Git for Multi-Layer Products

Software teams have spent the last decade debating where requirements should live. Jira and Confluence became the default answer for most organizations — until AI-assisted development started exposing real cracks in that model. With coding agents now consuming, generating, and acting on requirements directly, it’s worth revisiting the question.

The popular answer in developer circles is “put requirements next to the code.” That advice works beautifully for a single-service repo. It falls apart the moment your product spans a web app, iOS and Android clients, a set of backend services, a data pipeline, and an integration layer — which describes most non-trivial products.

This post lays out the honest trade-offs, then proposes a concrete model: a dedicated requirements repository, where each top-level business requirement owns layer-specific sub-requirements beneath it.

Table of Contents

The Case for Jira / Confluence

Jira and Confluence didn’t become industry standards by accident.

Built for non-technical stakeholders. Product managers, designers, compliance, and executives need to write and review requirements without touching a terminal or learning Markdown. The WYSIWYG editor and ticket workflows keep the barrier to entry low.

Mature workflow and process tooling. Sprint boards, approval flows, status transitions, notifications, and cross-team visibility are battle-tested. Enterprise governance — audit trails, sign-offs, regulatory evidence — is usually easier to satisfy in Jira than in a Git repo.

Rich linking across the business. Requirements link naturally to epics, OKRs, customer tickets, support escalations, and roadmaps — systems that live entirely outside the codebase.

Org-wide discoverability. Search and permissions in Confluence are designed for a broad audience, not just engineers with repo access.

Where It Breaks Down

  • Drift from reality. A ticket says one thing; the shipped code does another. Nothing enforces the link.
  • Weak versioning. Page history exists, but there are no real diffs, no branches, no pull-request-style review of a requirement change.
  • Poor machine-readability. Requirements end up scattered across prose, comments, attachments, and page trees — hard for tooling (and agents) to parse reliably.
  • Context switching. Engineers and agents must leave the working environment to find a “source of truth” that is often stale.
  • No structural relationship between layers. A requirement that spans web, mobile, and services becomes a ticket with a comment thread, not a structured decomposition.

The Case for Git-Based Requirements

Storing requirements as Markdown and YAML under version control — “docs-as-code” — has real advantages, and AI agents amplify most of them.

Real version control. Full diff history, blame, branching, and merge review. The same rigor you apply to code applies to the requirement.

Machine-native for AI agents. This is the decisive one. Coding agents read repositories natively. Structured Markdown with front-matter becomes directly consumable context — no API pagination against Jira, no scraping a Confluence export, no stale cache.

Reviewable change. Changing a requirement becomes a pull request with reviewers, discussion, and an approval record — which, incidentally, is often better audit evidence than a Confluence page history.

Automatable. Requirements-as-code can be linted, validated against a schema, checked for orphaned IDs, and used to generate test scaffolding or traceability matrices in CI.

Where It Breaks Down

  • Excludes non-technical stakeholders. Asking a product manager or compliance reviewer to author Markdown via pull requests is a genuine adoption barrier.
  • No native process layer. Git gives you no sprint board, no approval chain, no stakeholder notifications.
  • And the big one: “next to the code” does not survive contact with a multi-layer product.

Why “Requirements Next to the Code” Fails for Multi-Layer Products

Consider a straightforward requirement: “A member can update their payment method and see the change reflected immediately.”

That single requirement touches:

  • the web app (settings UI, validation, error states)
  • iOS and Android (platform-native payment sheets, different biometric confirmation flows)
  • a payments service (tokenization, PSP integration, idempotency)
  • a profile/account service (ownership, entitlement checks)
  • a notification service (confirmation email/push)
  • data and analytics (event schema, reporting)
  • compliance (PCI scope, audit logging, data retention)

If you co-locate requirements with code, you now have seven fragments of one requirement in seven repositories, with:

  • No single authoritative statement. Which repo holds the real acceptance criteria? All of them hold a slice; none holds the whole.
  • Guaranteed divergence. The iOS fragment gets updated; the services fragment doesn’t. Nobody notices for two sprints.
  • Broken traceability. Answering “what does the product actually promise here, and is it fully delivered?” requires grepping seven repos and reconciling by hand.
  • Permission mismatch. Product, QA, and compliance need to read and write requirements. They rarely have — or should have — write access to every application repo.
  • A hostile surface for AI agents. An agent working in the mobile repo has no visibility into the contract the services team committed to. It will confidently generate code against half a requirement.
  • Lifecycle mismatch. Code repos get archived, split, merged, rewritten in another language. Requirements outlive all of that.

The instinct behind “next to the code” is correct — requirements should be versioned, diffable, and agent-readable. The mistake is assuming proximity to one codebase is what delivers that.

The Real Shift: AI Agents Changed the Cost-Benefit Calculation

Historically, the Jira/Confluence trade-off was tolerable because humans were the primary readers of requirements, and humans tolerate ambiguity, staleness, and hunting across tools reasonably well.

Agents do not. When an engineering org relies on AI agents to turn requirements into code, three things become true:

  1. Machine-readability stops being a nice-to-have. An agent performs dramatically better against structured, versioned Markdown than against a rendered page behind a proprietary API.
  2. Freshness matters more than ever. An agent acting on a stale requirement doesn’t produce a wrong comment — it produces shipped code, tests that codify the wrong behavior, and a PR that looks convincing.
  3. Hand-written requirements are shrinking. Teams increasingly generate requirements with AI — from discovery calls, transcripts, support tickets, or even reverse-engineered from existing code. When the requirement is itself a generated artifact, the argument for a heavyweight human-authoring tool weakens, and the argument for a reviewable, versioned, structured artifact strengthens.

A fourth point matters specifically for multi-layer products: agents need the cross-layer contract, not just their slice of it. The mobile agent needs to know the API shape the services team committed to. The services agent needs to know the error states the web team will render. That shared contract has to live somewhere both can read.

Recommendation: A Dedicated Requirements Repository

Rather than scattering requirements across application repos or leaving them in Confluence, create one requirements repository per product (or per product line) that serves as the engineering source of truth.

The organizing principle: a top-level requirement captures the business intent and shared contract; layer-specific sub-requirements hang beneath it.

Why a Separate Repo Works

ConcernHow the dedicated repo addresses it
Cross-layer coherenceOne parent requirement holds the shared contract; layers decompose beneath it
Versioning & reviewFull Git history, PR-based review, diffs on requirement changes
Agent consumptionA single repo an agent can clone, index, or receive as context — the whole picture, not a fragment
Access controlProduct, QA, and compliance get write access here without touching application repos
TraceabilityStable requirement IDs referenced from commits, PRs, tests, and Jira
Lifecycle independenceSurvives repo splits, rewrites, and platform migrations
Stakeholder inclusionWeb-based Git editors, or a Jira-to-repo automation, keep non-engineers in the loop

Sample Hierarchy Structure

product-requirements/                      # the dedicated requirements repository
│
├── README.md                              # how to author, review, and consume requirements
├── CODEOWNERS                             # layer owners auto-assigned as PR reviewers
├── CONTRIBUTING.md                         # PR workflow, naming rules, review SLAs
│
├── .schemas/
│   ├── requirement.schema.json            # front-matter schema (validated in CI)
│   └── acceptance-criteria.schema.json
│
├── .github/workflows/
│   ├── validate-requirements.yml          # schema lint, ID uniqueness, broken-link check
│   ├── traceability-report.yml            # generates coverage matrix: req → code → test
│   └── sync-jira.yml                       # two-way status/link sync with Jira
│
├── glossary.md                            # shared domain vocabulary (high-value agent context)
│
├── standards/                             # cross-cutting, applies to every requirement
│   ├── accessibility.md                   # WCAG baseline
│   ├── security-baseline.md
│   ├── privacy-and-data-retention.md
│   ├── observability.md
│   └── performance-budgets.md
│
├── domains/
│   ├── membership/
│   │   ├── domain.md                      # domain overview, owners, boundaries
│   │   │
│   │   ├── REQ-MEM-014-update-payment-method/
│   │   │   ├── requirement.md             # ← TOP-LEVEL REQUIREMENT
│   │   │   │                              #   intent, scope, personas, business rules,
│   │   │   │                              #   end-to-end acceptance criteria, NFRs,
│   │   │   │                              #   open questions, decision log
│   │   │   │
│   │   │   ├── contracts/                 # the shared, cross-layer agreement
│   │   │   │   ├── api-payment-method.openapi.yaml
│   │   │   │   ├── events.asyncapi.yaml
│   │   │   │   ├── error-codes.md
│   │   │   │   └── state-machine.md
│   │   │   │
│   │   │   ├── layers/                    # ← LAYER SUB-REQUIREMENTS
│   │   │   │   ├── web.md                 # REQ-MEM-014-WEB
│   │   │   │   ├── mobile-ios.md          # REQ-MEM-014-IOS
│   │   │   │   ├── mobile-android.md      # REQ-MEM-014-AND
│   │   │   │   ├── service-payments.md    # REQ-MEM-014-SVC-PAY
│   │   │   │   ├── service-profile.md     # REQ-MEM-014-SVC-PRF
│   │   │   │   ├── service-notifications.md
│   │   │   │   ├── data-analytics.md      # events, schema, reporting
│   │   │   │   └── integration-psp.md     # third-party payment provider
│   │   │   │
│   │   │   ├── test/
│   │   │   │   ├── acceptance.feature     # Gherkin, machine-readable
│   │   │   │   └── test-strategy.md
│   │   │   │
│   │   │   └── assets/
│   │   │       ├── flow-diagram.md         # Mermaid, diffable
│   │   │       └── design-links.md         # Figma references
│   │   │
│   │   └── REQ-MEM-021-membership-renewal/
│   │       └── ...                        # same structure
│   │
│   ├── payments/
│   ├── learning-platform/
│   └── identity/
│
├── platform/                              # requirements with no single business owner
│   ├── REQ-PLT-003-sso-migration/
│   └── REQ-PLT-007-audit-logging/
│
└── archive/                               # superseded requirements, kept for traceability
    └── REQ-MEM-009-legacy-billing/

What Goes in the Top-Level Requirement vs. a Layer Sub-Requirement

requirement.md (top level) — the what and why:

  • Business intent and the problem being solved
  • Personas and scope (explicitly including what is out of scope)
  • Business rules that are true regardless of platform
  • End-to-end acceptance criteria, in Given/When/Then form
  • Non-functional requirements (latency, availability, accessibility, compliance)
  • Links to every layer sub-requirement, with status
  • Decision log — what was considered and rejected, and why

layers/*.md (sub-requirements) — the how, per layer:

  • Platform-specific behavior and constraints (iOS biometric confirmation differs from web)
  • UI states, validation, and error handling for that layer
  • The layer’s slice of the API/event contract, referencing contracts/
  • Layer-specific acceptance criteria and edge cases
  • Owning team and target repo(s)
  • Explicit dependencies on other layers

A Front-Matter Convention Agents Can Rely On

Every requirement file should open with structured metadata. This is what makes the repo an effective context source rather than a pile of prose.

---
id: REQ-MEM-014-IOS
parent: REQ-MEM-014
title: Update payment method — iOS client
layer: mobile-ios
status: in-development        # draft | approved | in-development | delivered | deprecated
owner: mobile-team
jira: MEM-4821
repos:
  - org/member-app-ios
contracts:
  - contracts/api-payment-method.openapi.yaml
depends_on:
  - REQ-MEM-014-SVC-PAY
authored_by: ai-assisted       # human | ai-assisted | ai-generated
reviewed_by: [j.doe, a.patel]
last_reviewed: 2026-09-12
---

The authored_by field matters more than it looks. When most requirements are AI-drafted, knowing which ones received genuine human scrutiny is essential for triaging risk.

Making It Work in Practice

1. Keep Jira and Confluence for what they’re genuinely good at

Epics, roadmaps, OKRs, sprint tracking, stakeholder communication, customer-facing commitments, and executive reporting stay where they are. Do not attempt a full migration — the organizational cost is high and the benefit is low.

Division of labor:

  • Jira owns the why now — priority, business justification, delivery status, who’s working on it.
  • Confluence owns the narrative — strategy documents, research, decision context for a broad audience.
  • The requirements repo owns the what and how — the precise, versioned, agent-consumable specification.

Where they conflict, the repo is authoritative for engineering work, because it’s the artifact that gets reviewed alongside implementation.

2. Automate the sync; never hand-maintain two copies

  • Creating a Jira ticket generates a requirement stub in the repo via automation.
  • The requirement’s front-matter carries the Jira key; CI keeps status fields aligned.
  • PRs in application repos reference requirement IDs; a bot posts the link back to Jira.

Two hand-maintained copies of a requirement guarantee two divergent requirements.

3. Wire traceability into CI

  • Commit messages and PR titles in application repos include the requirement ID (REQ-MEM-014-IOS).
  • A scheduled job in the requirements repo generates a traceability matrix: requirement → layer → repo → PR → test → status.
  • CI flags orphans in both directions: requirements with no implementing PR, and PRs referencing no requirement.

This matrix is also excellent audit evidence — often better than what Confluence produces.

4. Make requirement authoring an explicit step in the agent workflow

Since most requirements are now AI-assisted rather than hand-written, build the authoring step into the workflow rather than leaving it to a prompt in someone’s chat history:

  1. An agent drafts the top-level requirement and layer sub-requirements from the ticket, discovery notes, or transcript.
  2. Layer owners review via pull request — CODEOWNERS routes each layer file to the right team.
  3. Only after merge does implementation begin, with the merged requirement as agent context.

The critical discipline: the merged, reviewed artifact is the requirement — not the prompt, not the chat log, not the agent’s summary.

5. Give non-technical stakeholders a path in

  • Browser-based Git editing with a PR template handles most casual edits.
  • For the rest, a lightweight form or Jira-to-repo automation generates a draft that engineers refine.
  • Rendered documentation (MkDocs, Docusaurus, or Backstage TechDocs) gives read-only stakeholders a clean, searchable view without requiring repo literacy.

6. Keep application repos thin and pointed

Each application repo carries a small REQUIREMENTS.md that lists the requirement IDs it implements and links to the requirements repo. If you use agent configuration files (CLAUDE.md, AGENTS.md, or similar), point them at the requirements repo so agents pull the full cross-layer context by default rather than working from a fragment.

Agents Automate Most of This Across Repos

The model above is a lot of moving parts: stubs, schemas, contracts, layer files, Jira keys, a traceability matrix, and a change that lands in seven application repositories. People should not be the courier between those repos. An agent that can read the requirements repository and every application repo named in repos: can carry most of the work this post describes. What remains for people is the part that was always the point: deciding what the product promises, and approving the artifact that says so.

Read the whole requirement, then work in one repo

An agent opened in member-app-ios should not stop at layers/mobile-ios.md. With the requirements repo in reach, it follows parent and reads the rest before it writes code:

  • the top-level requirement.md — intent, scope, and end-to-end acceptance criteria
  • contracts/ — the API, events, error codes, and state machine every layer shares
  • each depends_on layer, so it sees what the payments service actually committed to
  • standards/ and glossary.md, which apply to every requirement

That is the practical fix for the hostile surface described earlier. The mobile agent generates against the shared contract, not against the slice that happens to live in the repo it was opened in.

The same read works in the other direction. An agent in the payments service reads the error states web and mobile will render, because those layer files sit next to its own.

Change the contract once, open the rest of the PRs

When a shared contract changes — a new error code, a field added to the payment-method API — the agent treats that as one change with several homes. repos: and depends_on already name every codebase involved. From that list it opens a coordinated set of pull requests:

  1. The contract and any affected layer files, in the requirements repo.
  2. The implementing change in each application repo that consumes the contract: web, iOS, Android, and the services.
  3. A short update to each repo’s REQUIREMENTS.md when a layer is added, split, or marked delivered.

Reviewers still approve each pull request in the repo they own. The agent is what keeps the set consistent, so the iOS fragment does not move ahead while the services fragment sits still for two sprints.

The chores in this post are agent jobs

Most of the mechanics above are repetitive, structured, and specified well enough for an agent to run them across repositories:

Work described in this postWhat the agent does across repos
Requirement draftingDrafts the top-level file and each layer file from a Jira ticket, a transcript, or discovery notes, and opens one pull request
Schema and hygieneLints front-matter against .schemas/, checks that IDs are unique, and flags broken links to contracts/
Jira syncCreates the requirement stub when a ticket opens, writes the Jira key into front-matter, and posts implementing PR links back onto the ticket
TraceabilityWalks requirement → layer → repos → pull requests → tests, and writes the matrix
Orphans, both directionsFlags a requirement with no implementing PR, and an application PR whose title cites no requirement ID
DivergenceNotices that mobile-ios.md changed while service-payments.md and its repo did not, and opens the missing follow-up
Test scaffoldingTurns acceptance.feature into test stubs in the repositories named for that layer
Agent configurationKeeps AGENTS.md or CLAUDE.md in each application repo pointed at the parent requirement and its contracts
Stakeholder viewRegenerates the rendered docs site from the merged repo, so readers see the reviewed spec rather than a chat log

Status fields, cross-repo searches, and stale layer files are the agent’s job. CI still enforces the checks; the agent is what prepares the change and repairs the drift before a person has to go looking.

What stays with people

Cross-repo automation does not replace the review. The agent drafts, links, and implements. People still own:

  • Intent and scope. What problem this solves, and what is explicitly out of scope.
  • The merge on the requirements repo. The requirement is the merged, reviewed file. The prompt, the chat log, and the agent’s summary are drafts until that merge.
  • Cross-team judgment. Whether iOS should diverge from web, whether a contract change stays backward compatible, and whether compliance scope changed.
  • When the full structure applies. A small, single-repo change can take the lightweight path. A person, or a written rule a person approved, decides that — not the agent, by default.

Give the agent read access to the requirements repo and to every repository listed in repos:, point its configuration there by default, and keep merge rights with the reviewers CODEOWNERS already names. The cross-repo work in this post then becomes execution. The scarce part — what the product promises, across every layer — stays with the people who can be held to it.

Honest Trade-Offs of the Separate Repo

This model is not free. Be clear-eyed about its costs:

  • It is another repo to govern. Ownership, review SLAs, and hygiene need an explicit owner, or it becomes a graveyard.
  • Physical separation from code reintroduces drift risk. The mitigation is CI traceability checks and a hard rule that requirement changes and implementation PRs cross-reference each other — but the risk is real and you must actively manage it.
  • Some duplication with Jira is unavoidable. Keep it to identifiers and status only; automate the rest.
  • Structure can ossify into bureaucracy. Not every change needs a full requirement folder. Define a lightweight path for small changes and reserve the full structure for anything spanning more than one layer.
  • Adoption requires a real mandate. A requirements repo that half the teams ignore is worse than Confluence, because now there are three sources of truth instead of two.

A Phased Path Forward

  1. Pilot (4–6 weeks). One domain, two or three genuinely cross-layer requirements. Prove the structure before standardizing it.
  2. Codify. Lock the front-matter schema, ID convention, and PR workflow. Add CI validation.
  3. Automate. Jira sync and the traceability matrix. Do not scale without these.
  4. Integrate with agents. Point agent configuration at the requirements repo; measure whether generated code quality improves.
  5. Scale by domain, and only forward. New requirements go into the repo. Migrate historical requirements only where there’s active work — bulk-migrating dead Confluence pages is wasted effort.

Bottom Line

Jira and Confluence aren’t going away, and they shouldn’t. They remain the right tools for business process and stakeholder-facing work. But treating them as the source of truth for engineering requirements is an increasing liability when agents are doing the implementation.

“Put requirements next to the code” gets the principle right and the location wrong. For any product spanning web, mobile, services, and data, a dedicated requirements repository with layer-specific decomposition beneath a top-level requirement delivers what co-location promises — versioning, diffs, review, machine-readability — without shattering a single requirement across seven codebases.

The teams that get the most leverage from AI agents will be the ones who stop treating requirements as static tickets and start treating them as structured, versioned, reviewable artifacts that describe the whole system rather than one slice of it. Those same agents can then carry the work across repositories: drafting the layers, keeping the shared contract and the implementing pull requests in step, and flagging the slice that drifted.

“The merged, reviewed artifact is the requirement — not the prompt, not the chat log, not the agent’s summary.”-Rushi

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>