Already keep your design docs in GitHub?

When one proposal becomes several pull requests, those connections give the next reviewer somewhere to start. Free includes one design doc. No credit card required.

GitHub already gives you a strong foundation

Markdown files are easy to version, review and keep beside code. Pull requests preserve the discussion, show the diff and collect approvals. CODEOWNERS can route reviews to the people responsible for a file.

GitHub also supports Mermaid diagrams, issue tracking and Projects. A team with clear conventions can build a substantial design process around those tools.

ArchDocs becomes useful when you want those records organized around the engineering change and the system it affects. Open a service and find its linked designs. Open a design and see its questions, plan and recorded changes. Give an agent that context before it starts another task.

What each approach gives you

GitHub's reviews, work tracking and agent instructions are established capabilities. The choice is how much of the design workflow you want to assemble and maintain around them.

Follow one change beyond its first pull request

Your team wants to shorten the response window for carriers using an API. Older EDI integrations must keep their existing window.

The design touches Dispatch Service and Carrier Gateway. One question remains: what happens when a carrier accepts after the deadline?

In GitHub, you can write the RFC, discuss that question, link the implementation issues and review the pull requests. Your team decides how to keep the RFC, issue states and implementation history aligned.

In ArchDocs, the same change has a design record:

• The spec mentions Dispatch Service and Carrier Gateway.
• The unresolved question has a named owner and stays with the design.
• The implementation plan identifies the intended changes.
• People and agents record work against those targets.
• A reviewer returns to the record to see what still needs explaining.

For example:

| Target | Planned? | Recorded change? | | ---------------- | -------- | ---------------- | | Dispatch Service | Yes | Yes | | Carrier Gateway | Yes | No | | Tracking Service | No | Yes |

The reviewer now has two concrete follow-ups: confirm the Carrier Gateway work and understand why Tracking Service changed.

A missing record does not mean the implementation is missing. It makes the gap visible so someone can resolve it.

Illustrative example using fictional sample data.

Give the next agent the reasoning behind the task

An agent can already read Markdown in your repository. Custom instruction files can also supply project conventions and guidance.

ArchDocs adds access to the design's recorded state: its plan, open questions, linked decisions and reported work. Task context on Team and above groups records as Current, Related, Uncertain or Historical and explains why they were included.

That lets the agent distinguish a proposal awaiting approval from a decision a person approved, or notice an unanswered question before building on an assumption.

Agents can contribute through MCP and leave attributed reports. Human approval remains a separate action. Your prompt or agent skill still needs to tell the agent when to read context and update the record.

When keeping everything in GitHub makes sense

Stay with repository design docs when your team can reliably find the relevant proposal, follow its decisions and understand its implementation through the workflow you already have.

GitHub is especially useful when reviewing documentation and code in the same pull request is a priority. Adding another workspace also adds another place to maintain.

Consider ArchDocs when these questions keep taking work to answer:

• Which designs and decisions are linked to this service?
• Which questions remain unresolved?
• How does the recorded implementation compare with the plan?
• What should the next engineer or agent read before continuing?

Start with one change that exposes those problems. You can evaluate the value before moving more documentation.

Use ArchDocs alongside GitHub

Keep implementation branches, code review and CI in GitHub. Use ArchDocs for the design record and its connections to your architecture.

On Business and Enterprise, link the relevant pull requests to the design doc and inspect their state and check results there. A passing check retains its source and commit; it does not establish that the whole design was implemented correctly.

For architecture diagrams, Team and above can import diagram YAML from GitHub. That sync runs from GitHub into ArchDocs. It does not synchronize design-doc Markdown in both directions.

Start with the plan you need

Free includes one design doc, its questions, planned and recorded changes, and MCP access.

Team adds unlimited design docs, task context and the GitHub integration.

Business and Enterprise add formal design reviews and approvals, plus linked pull request and CI evidence from GitHub.

Work logs come with design docs on every plan. The in-app Work Log tab is currently in early access.

Compare plans

Common questions

Could we build this workflow with templates, Issues and GitHub Actions?

Yes. Templates, Issues, Projects and automation can support a sophisticated process. ArchDocs gives you a shared structure for design questions, architecture links, recorded changes and agent context. Evaluate whether maintaining those connections yourself is worthwhile for your team.

Do we have to migrate every existing RFC?

No. Start with a new change. Reference earlier documents where useful and bring relevant decisions into the record as you need them. You can also import a Markdown implementation plan through MCP.

Does ArchDocs automatically know everything that changed?

No. People and agents record changes, and you choose which pull requests to link. Documented dependencies come from saved diagram references. ArchDocs organizes that information and exposes gaps for review.

Can our coding agent keep working in the repository?

Yes. It can work in the repository while using ArchDocs through MCP to read the design, raise questions, record changes and leave a handoff.

Try it on the next change that spans several pull requests

Create one design doc. Name the services it affects. Write down the unresolved question and the implementation plan.

As work lands, record the changes and see whether the next review is easier to pick up. One design doc on Free. No credit card required.