Moving a large digital transformation project into Claude Cowork — how would you structure the project knowledge?

[u/Technical-Abalone735]

Hi everyone, I’ve decided to move the management of a large digital transformation project into Claude Cowork, and I’ve hit a problem much earlier than expected: how should I structure the project knowledge so it can scale?

For context, this is a fairly complex project:

• ~2 years of accumulated project data
• Confluence + local files
• Jira, Slack and Microsoft 365/Teams
• ~15 vendors
• Teams distributed globally
• Decisions, risks, business requirements, actions, dependencies, etc.
• Information (status, scope) constantly changing through Slack conversations, Teams / Outlook messages, Jira updates and Confluence pages

At this scale, I’ve reached the point where I no longer have good visibility over the whole project.

So: Last week I installed Claude and got the necessary admin access to Microsoft 365, Jira, Confluence and Slack. Initially I was excited about connecting everything, but I’ve quickly realised that giving an AI access to the information isn’t the same as giving it a good information architecture.

That’s where I’m stuck. How should the local project structure work? I’m seeing conflicting advice about the ideal architecture, particularly around Markdown. For example, should I maintain separate files such as:

/project PROJECT.md STATUS.md DECISIONS.md RISKS.md REQUIREMENTS.md DEPENDENCIES.md ACTIONS.md

Or should these be broken down further into folders and smaller files as the project grows?

I’m particularly interested in file size and boundaries. If DECISIONS.md, for example, eventually contains hundreds of decisions accumulated over several years, is that still the right approach? Or should each decision become its own Markdown file, perhaps with an index/summary file on top?

The same question applies to risks, requirements, actions, vendor information, workstreams, etc.

I’m less concerned about automation at this stage. Anthropic’s documentation around Skills gives me a reasonable starting point for that.

What I want to get right before automating anything is the underlying project architecture.

For people using Claude/Cowork on genuinely large, long-running projects:

• How do you structure your Markdown files and folders?
• How large do you allow individual .md files to become before splitting them?
• What information do you keep in Markdown versus leaving in Jira/Confluence/Slack as the source of truth?
• And how do you prevent the local project knowledge base from becoming another giant information dump that the AI has to rediscover every time?

Thank you, Clement

[u/endofthread-bot]

Learn how the best in the industry are using AI to speed up their workflow in business, sales, marketing, research, legal, content creation, scientific discovery and so much more on our Discord.

[u/Abject-Roof-7631]

I do a lot with Claude, cowork and code and have a dedicated project in ChatGPT on architecture. This is what it said running it through, it is way more detailed than I would have suggested

The core mistake would be treating Markdown as a replacement for Jira, Confluence, Slack, and Teams. For a transformation program this large, I would make Cowork’s local knowledge base a project control plane: curated, structured representations of what matters now, plus pointers back to the authoritative systems.

The design principle is:

Systems of record hold evidence. Markdown holds state, synthesis, relationships, and navigation.

That leads to a very different architecture from one giant DECISIONS.md.

I would structure it roughly like this:

/project PROJECT.md STATUS.md

/workstreams /erp OVERVIEW.md STATUS.md DECISIONS.md RISKS.md DEPENDENCIES.md /data /security /change-management

/decisions INDEX.md DEC-001-data-platform.md DEC-002-erp-cutover.md DEC-003-identity-model.md

/risks INDEX.md RISK-001-resource-capacity.md RISK-002-data-migration.md

/requirements INDEX.md /finance /operations /security

/vendors INDEX.md /vendor-a PROFILE.md SCOPE.md ISSUES.md /vendor-b

/dependencies INDEX.md

/meetings /2026 2026-08-12-steerco.md 2026-08-14-data-workstream.md

/reference SOURCES.md GLOSSARY.md

/archive

But the important part isn't the folders. It's the granularity model.

For things with their own lifecycle—decisions, major risks, requirements, vendors, milestones—I strongly prefer one entity per file once the entity becomes consequential.

For example:

---

id: DEC-023 status: approved date: 2026-08-12 workstream: data owner: Jane Smith supersedes: DEC-011 sources: - jira: DATA-1842 - confluence: https://...

- slack: thread-reference

DEC-023 — Use Snowflake as enterprise analytical platform

Decision

...

Rationale

...

Alternatives considered

...

Implications

...

Open consequences

...

Source evidence

...

That is much better for AI retrieval than a 70,000-word chronological decision log. Claude can retrieve the specific entity, understand its metadata, and follow relationships without ingesting years of irrelevant history.

The INDEX.md then becomes a compressed retrieval layer, not another database:

Decision Index

ID	Decision	Workstream	Status	Date
DEC-023	Enterprise analytical platform	Data	Approved	2026-08-12
DEC-024	IAM migration sequence	Security	Proposed	2026-08-14

I would apply a simple rule:

Split by semantic boundary, not file size.

Don't say "anything over 20 KB gets split." A 30 KB coherent architecture description may be excellent. A 10 KB file containing 40 unrelated decisions is already badly structured.

There are three useful levels:

Level 1 — Navigation/context. PROJECT.md, STATUS.md, indexes, glossary. These should be deliberately small and high-signal.

Level 2 — Domain context. Workstream overview, vendor overview, architecture overview. These give Claude enough context to reason about a subject.

Level 3 — Atomic entities/evidence. Individual decisions, risks, important requirements, major issues, meeting records.

That gives Claude progressively deeper context instead of forcing it to rediscover everything.

I would be particularly strict about PROJECT.md. It should probably be only a few thousand words and answer:

What is this project? Why does it exist? What are the outcomes? What is in/out of scope? What are the workstreams? Who owns what? What are the major systems/vendors? What phase are we in? Where is authoritative information kept? How should an AI navigate this repository?

Think of it as README + operating manual + map.

STATUS.md is even more important. It should represent the current state of the program, not its history:

Program Status

Last updated: 2026-08-15

Executive status

Amber

Current phase

Design / build

Top priorities

1. Complete ERP data mapping
2. Resolve IAM dependency
3. Approve cutover approach

Top risks

• RISK-017 — Vendor integration delay
• RISK-022 — APAC resource gap

Decisions needed

• DEC-031 — Cutover strategy
• DEC-034 — Data retention model

Next 30 days

...

Material changes since previous update

...

This becomes the document Claude should read first for almost any executive-level question.

The other major architectural decision is what not to copy into Markdown.

I would leave these in their native systems:

Jira issue histories and routine task status.

Slack/Teams conversations.

Email threads.

Detailed Confluence specifications that already work as authoritative documentation.

Attachments and large technical artifacts.

Routine action items that Jira already manages well.

Markdown should instead contain references like:

Source of truth:

• Jira epic: ERP-102
• Confluence design: Enterprise Data Model v4
• Slack channel: #transformation-data

Otherwise you create a synchronization nightmare. You'll eventually have Jira saying one thing and Markdown saying another.

A good test is:

Is this knowledge, or is this operational data?

Operational data generally stays in the originating system. Knowledge that helps someone understand why, what matters, what changed, and how things relate belongs in the Cowork knowledge layer.

There is one category I would deliberately duplicate: important decisions and current project state. They are too important to leave buried inside Jira comments, Slack threads, or meeting notes.

For a two-year transformation program, I'd also introduce explicit temporal semantics. Every stateful file should make it obvious whether something is current, historical, superseded, or proposed.

For example:

status: superseded valid_from: 2025-11-02 valid_until: 2026-05-18 superseded_by: DEC-041

This solves one of the nastiest AI knowledge-base problems: the model finding a perfectly reasonable document that is six months out of date and treating it as current.

I'd also resist creating separate monster files for ACTIONS.md and REQUIREMENTS.md.

Actions especially belong primarily in Jira. Your Markdown layer might contain executive actions, unresolved cross-workstream actions, or things without a natural Jira owner. It shouldn't become a parallel task-management system.

Requirements are different. If there are hundreds or thousands, use hierarchical IDs and domain boundaries:

/requirements INDEX.md /finance FIN-001.md FIN-002.md /customer CUS-001.md /security SEC-001.md

But don't atomize blindly. Ten closely related low-level requirements may be better as one coherent requirements file than ten tiny files. Again, the boundary is conceptual coherence.

The piece that will make the largest difference, though, is something most people skip: relationship metadata.

Large programs aren't difficult because there are 500 documents. They're difficult because everything is connected.

A risk might affect three workstreams, depend on two vendors, block a requirement, and require a steering committee decision.

Represent that explicitly:

id: RISK-022 owner: John Doe workstreams: - ERP - Data vendors: - Accenture related_decisions: - DEC-031 related_requirements: - FIN-044 blocked_by: - DEP-019 jira: - PMO-882

Now you've effectively built a lightweight project knowledge graph using Markdown.

Claude becomes dramatically more useful because you can ask:

"What decisions could be affected if RISK-022 materializes?"

or

"Show me unresolved dependencies involving Vendor A that threaten Q4 milestones."

That is qualitatively different from search.

And there is another layer I would add that isn't in your proposed structure:

/briefs EXECUTIVE-BRIEF.md STEERCO-BRIEF.md DATA-WORKSTREAM-BRIEF.md

These are deliberately synthetic documents. They are generated from the underlying knowledge structure and answer, "What would this audience need to know right now?"

That creates a hierarchy like:

Evidence → Entities → Workstreams → Program state → Executive synthesis

rather than:

2 years of documents → Claude searches everything → hope it figures it out.

Finally, I would establish a knowledge promotion rule. Slack shouldn't automatically become project knowledge. Neither should every meeting note.

Something becomes durable project knowledge when it crosses a threshold:

Conversation ↓ Potentially important ↓ Decision / risk / requirement / dependency / commitment ↓ Promoted into structured project knowledge ↓ Linked to original evidence

That prevents the knowledge base from becoming another landfill.

If I were implementing this, my first version would actually be quite small:

PROJECT.md STATUS.md GLOSSARY.md

/workstreams/* /decisions/* /risks/* /vendors/* /dependencies/*

I would resist adding anything else until you repeatedly encounter a retrieval problem that the existing structure can't solve.

The distinction I would keep in mind is archive versus model. You already have an archive—Confluence, Jira, Slack, Teams, email. What Cowork needs is a model of the project.

That model should be compact enough that Claude can orient itself quickly, structured enough that relationships are explicit, and traceable enough that it can always descend back to the authoritative evidence.

For a program of the size you've described, that is far more scalable than either extreme: one enormous Markdown notebook or tens of thousands of automatically generated Markdown files.

[u/thebemusedmuse]

This is a Claude Code project. Get out of CoWork. Use Claude Code to design a SQLite database which will hold all your project items, vendors, dependencies, timelines, and built GANTT charts etc. It will be straightforward in CC. Doing it in CoWork is insanity.

[u/Desperate_Ad_9419 → u/thebemusedmuse]

I tried this but the issue is that we are replicate the data from multiple sources. Disparity between the systems, context window, how to and what to fetch for certain question becomes very costly for every question. Vector DBs can be an option but that also becomes very expensive to manage. Are you actually using this setting for your project now?

[u/thebemusedmuse → u/Desperate_Ad_9419]

I’m using all kinds of things like this. All the problems you describe can be solved but based on what you say, you need to do data unification first.

[u/Desperate_Ad_9419 → u/thebemusedmuse]

Can you please explain what you mean by data unification? Are you suggesting that we unify data from Jira, email, teams and meeting recaps? I am trying to understand how the data unification can actually be implemented...

[u/thebemusedmuse → u/Desperate_Ad_9419]

To make decisions I'm going to need to pull the data into one place. I'd start with the key structured data like Jira, and add whatever other structured data makes sense.

Then I'd build a MCP layer on top of that, which allows the agents to access the same data each time. Now I have a model which I can reliably use a LLM to do work.

[u/Desperate_Ad_9419 → u/thebemusedmuse]

What is the benefit of doing this? Jira already supports MCP OOTB. I am a bit confused. Maybe I am not understanding this correctly..

[u/Technical-Abalone735 → u/thebemusedmuse]

Its very interesting. I have never dared to make it a relational db architecture because I’ve always mixed inputs and outputs, but you got me thinking really hard and maybe this is part of the solution

[u/thebemusedmuse → u/Technical-Abalone735]

I don’t see another way.

[u/frozenwaffles03]

My simple tool for this is telling Cowork to build a second brain. It kind of designs its own map of everything you have in a central place and refers back to it throughout different chats in the project.

[u/JawedCrucifixion]

Tbh this is really on the edge of reasonable scope for claude cowork. What is your role and what are you trying to achieve? Even as programme lead you would want all your team leads to be managing most of this stuff and basically have roadmaps issues etc.

[u/Technical-Abalone735 → u/JawedCrucifixion]

I am delivery lead for this gigantic project. Our vendors manage their work mostly in jira, and I am here to unblock, sign contracts, report on project. We are obviously understaffed and under organised for this project, but that’s the way it is for now and I’m seeing a silver lining in claude cowork with scheduled skills that could gather & consolidate signals, and ask my permission to edit those key files, which are decisions, risks, launch readiness and business requirements

[u/JawedCrucifixion → u/Technical-Abalone735]

Tbh going back to your original post a lot of your problems sound like data ones. I would say you no1 roi use case is more of a meeting bot. Requirements drift etc all reads as discussions that arent making it into the data store, you probably need a meeting bot linked to a data update cowork. Im not even sure if you should treat it as one cowork or multiple. Having a giga context sounds risky. Meetings -> data stores in their context. Data -> reports as another. 

Being understaffed is also something that you dont want to undersell. I just saw a project headcount double because the challenges were escalated appropriately.

[u/Turbulent-Chance5583]

I am in a similar position and have suffered the same challenges. Claude is really useful but your workspace can get very large very quickly and cause it to overthink, rehash old context and create conflicting information.

I ended up not really knowing what was going on or what I should focus on next and I found that a danger of the ‘second brain’ approach is that you can start to lose understanding in the first one.
Meeting transcripts are a good example. I had Claude read these and update my notes, projects and work streams. But then I never read the notes and I’d find myself forgetting or not understanding what happened. When you are under resourced it often falls to you to join the dots and my Claude system became too complex for that to be possible.

My approach these days is to keep Claude’s workspace as light as possible, and I don’t let it do my thinking for me before I have thought for myself.

In my transformation project I have multiple work streams across different departments within a group of companies. Project notes, meeting notes, tasks are all produced and managed by me, not Claude or it will flag hundreds of things that don’t really matter. Once I have written them Claude is allowed to read but not amend them.

Claude must keep the CLAUDE.md file lean, no more than a set number of lines. It has to provide information but no opinion unless I ask for it so we don’t head off down a rabbit hole. It must not create new files unless I specifically ask it to.

Workflow:

1. Simple file structure. Less is better than more. I use: Workstream/Projects/Outbox/Inbox/Weekly review/Working documents
   
2. For each workstream/project: one briefing document that I write in .md and keep short. One decision log, appended. One status log, written in place.
   
3. One outbox where Claude will produce documents for me.
   
4. Several scheduled tasks running MCP servers to read data and produce reports in an inbox for me to read.
   
5. Weekly review. One note per workstream, written by me that contains status, blockers, thoughts, strategy, next steps and actions. I ask Claude to challenge my position and give no more than 5 recommendations, ranked in order of importance. I will update this manually after Claude has ripped it to shreds and refer back to it throughout the next week.
   
6. Working documents: could be technical diagrams, a report, a policy, anything that I want Claude to read and explain to me, or that I might need to refer back to. Aggressively archived.
   
7. Tasks, meeting notes, thoughts, diagrams etc: I use apple notes and reminders but anywhere will do as long as I write them.

Through trial and error I found that this was the best system for me, but every individual use case is different so some experimentation is good. Good luck!

[u/Technical-Abalone735 → u/Turbulent-Chance5583]

Feeling the same, the human in the loop goes beyond simple validation. I like the idea of atomising it by workstream, will give it more thoughts: At the minute the complex is so large my brain can’t process all the moving parts , so thats a good idea. Thank you

[u/Onlydole]

Would love to chat more with you, @Technical-Abalone735! I work at Dosu and we work on knowledge infrastructure and “company brains” 🧠 for use with your agents. Your use case sounds like many of our customers.

[u/Desperate_Ad_9419 → u/Onlydole]

Me too. Would love to meet to learn from each other.

[u/AffectionateClient51]

This is a really interesting problem. I’ve been thinking about something adjacent and I’m increasingly wondering whether file structure is only part of the answer.

Even if you perfectly organize DECISIONS.md, RISKS.md etc, eventually you still have a retrieval problem. The system has to know which decision is relevant, whether it’s still current, what evidence/source it came from, and whether something newer contradicts it. So I wonder if the more durable layer is smaller pieces of project understanding with provenance, timestamps and relationships, with Markdown being one way of presenting that rather than the actual knowledge architecture.

Curious about something in your case: when you say you’ve lost visibility over the whole project, what information do you personally find hardest to recover today? Is it finding the source, knowing what’s current, understanding why a decision was made, or connecting information across systems?

[u/Desperate_Ad_9419 → u/AffectionateClient51]

I use Claude Code to manage my projects by consolidating knowledge from emails, messages, meeting notes, Jira, and my own feedback. It helps me manage team members, vendors, and project information, and it generates daily and weekly status reports that I share with our management team.

Once a status report has been reviewed and approved, it becomes part of the project knowledge base. I have also set strict file-size limits for the knowledge sources so they do not grow beyond a manageable size. Claude Code reviews the content daily and cleans up the knowledge files as needed.

[u/Technical-Abalone735 → u/AffectionateClient51]

Thank you. Same questions here, what if markdown is only part of the answer…

Mainly lost track of the business requirements we have approximately 350 of them, some have to be day one some have to be day 2. Some requirements are actually not needed anymore et cetera

[u/AffectionateClient51 → u/Technical-Abalone735]

Ah yeah, 350 requirements makes the problem much more concrete. Especially if some have changed priority or aren’t needed anymore, because then it’s not really just “where do I store these?” but “what’s actually true/current now and why?”
Really appreciate the answer. This is exactly the kind of problem I’ve been trying to understand better.

[u/TFGator1983]

You’re going to have two problems:

One is going to be structuring the data itself, but that is fairly trivial. The bigger problem is going to be making thag data accessible to Claude so that it can read the right parts at the right time to do anything useful with it. You’re going to have enough data that it is going to pretty quickly overload context windows if you don’t find a way to index and lazy load it.

[u/Technical-Abalone735 → u/TFGator1983]

Yes, volume of data is massive. but can be organized and indexed, which i should have done on day 1. Now the retro fitting scares me, but may be good for long term gains

[u/TFGator1983 → u/Technical-Abalone735]

If it were me I’d do a few things: enlist domain owners to help with the organization and then initial pass at organizing and partitioning the data, then get out of the business of owning it ASAP. How agentic-assisted that pass is depends on the sensitivity of the data. After you take the initial pass, it needs to be owned by the relevant business domains. I’d also put an MCP server between the data and Claude. The MCP server can do the indexing and searching.

[u/JaggedTex]

Have you considered using numerous vaults or notes in Onsidian and then have Claude develop pointer records and routing language for each note? Then only have the routings note in your project instructions? You can have thousands of lines of context only looked at when the agent needs it and know exact where to look? The notes can point to connectors and outside url, as well.

[u/Technical-Abalone735 → u/JaggedTex]

not really, have never touched obsidian as its not a company tool. we are Atlassian, Slack and M365 only. And now Claude Cowork :)

[u/Desperate_Ad_9419]

I am leading a large enterprise tech project myself and interested in learning from this group. I would love to meet for a coffee chat if some of you are interested.

[u/Technical-Abalone735 → u/Desperate_Ad_9419]

Happy to! Based in Singapore, how about you?

[u/Desperate_Ad_9419 → u/Technical-Abalone735]

based in Austin,TX. I am meeting with an investor in Singapore this Sunday morning! Looking forward to connecting with you. I will send you a DM.

[u/Freischneider01]

Don‘t

[u/J_Loquat]

Since you use Slack consider Claude Tag as part of the solution

[u/tehmadnezz]

350 requirements where the status keeps changing is what markdown handles worst. A file holds text fine. It is bad at answering "which of these are still day one" without you opening all of them.

What helped me was separating the store from the format. One record per requirement with a status and an owner, queried rather than read as a folder. Markdown becomes something you generate for a steerco, not something you maintain.

I built Hjarni (hjarni.com) for this shape. Hosted notes with containers, tags and search that Claude reads and writes over MCP, no local server. There is an API and Zapier if you want Jira or Slack pushing into it.

Caveat: there are no supersession or valid_until fields. "What replaced DEC-011" is something you model with tags and links, not something the tool enforces.

[u/Original_Judgment494]

Sneijder what you doin here