· 7 min read
From Experiment to Documentation AGENTS.md for Docs
I love writing blogs but I do not like writing technical documentation. It is kind of weird, perhaps it has to do with the fact that blogs are more personal and less formal, bit at some point I gave up figuring out why. I have written a lot of docs in my career as, while I hate it, it still is a good way to capture important decisions and makes sure someone else can work with your solutions. To speed up I have been using templates and tools to assist, but in the end it still felt like a chore. And while AI will not solve all of the problems, you can quickly get a draft that only requires minor tweaks as so much of the details around the Power Platform are already captured in the system and the metadata.
A quick recap
In a previous blog, I explored the Power Platform CLI and the MCP server. In that blog the focus was pulling out solution metadata and using that as a reliable source of truth. This blog picks up from there and answers a simple follow-up question: what can you actually do with that metadata? Other than asking for some recommendations. So I decided to experiment with using that metadata as a starting point for architecture documentation, and capture the most important things into an AGENTS.md file, a standard file that describes the purpose of the agent, the expected structure of the documentation, and the level of detail that’s considered good enough.
Since Power Platform projects you can quickly create new apps, flows and other artifacts keeping up with documentation can be hard, but in the end delivering a solution to production means that there has to be some documentation. And given that much lives in metadata I gave it a try.
The idea: AGENTS.md as a starting point
The goal of an agents.md file is to give the agent a clear instruction on what to do, and how to do it. It’s a simple contract between you and the agent, where you define the scope and expectations of the documentation. In my case in order to write proper documentation I figured we should use the TOGAF architecture framework as a basis, and then fill in the details based on what the agent can extract from the metadata.
The MCP server contains tools to export solutions as we have seen in the previous blog, so the agents.md contains the following steps and expectations for the agent:
- Write documentation and generic instructions
- Expectations around the structure of the documentation (TOGAF-aligned) including a file structure
- A clear indication of the tools the agent can use
- Instructions to flag assumptions or missing information that can’t be derived from the metadata using a ⚠️ icon.
Setting up the agents.md
The setup is simple:
- An
AGENTS.mdfile in the repo - The Power Platform MCP server enabled
## 1. Purpose
This agent generates **TOGAF-aligned architecture documentation** for a **Microsoft Power Platform solution** using metadata retrieved via **PAC CLI (MCP server)**.
The agent MUST:
- Export the Power Platform solution as the single source of truth
- Use PowerShell to extract the exported solution using `Expand-Archive`
- Analyze extracted Power Platform solution
- If there are multiple apps (additional zip files) repeat the extraction and analysis for each app
- Map components to TOGAF architecture domains
- Produce a **structured but adaptable documentation set**
- Generate documentation suitable for **architecture governance**
---
## 2. Architecture Framework
- TOGAF 9.x / 10
- Architecture Development Method (ADM)
- Covered phases:
- Preliminary
- Phase A – Architecture Vision
- Phase B – Business Architecture
- Phase C – Application & Data Architecture
- Phase D – Technology Architecture
---
## 3. Power Platform Connectivity (PAC CLI via MCP)
### Authentication
Assume handled already, agent has access to necessary credentials. If not available, agent MUST explicitly state this as a blocker.
The exported solution is the **single source of truth**.
---
## 4. Condensed Documentation Structure (MANDATORY)
### 4.1 Root Structure
```text
/docs
01_Context_and_Vision.md
02_Business_Architecture.md
03_Application_Architecture.md
04_Data_Architecture.md
05_Technology_Architecture.md
06_Security_and_Integration.md
07_Deployment_and_Governance.md
08_Appendix.md
```
This structure MUST be created exactly as shown.
---
## 4.2 Mandatory Chapter Structure per File
Each document MUST use the following internal structure.
Sections may be empty if not applicable, but MUST be present.
```markdown
# <Document Title>
## 1. Purpose
## 2. Scope
## 3. TOGAF Phase Mapping
## 4. Architecture Principles
## 5. Current State (Baseline)
## 6. Target State
## 7. Key Decisions and Rationale
## 8. Risks and Assumptions
## 9. Open Questions
## 10. References
```
---
## 5. File-by-File Content Requirements
### 01_Context_and_Vision.md
**TOGAF:** Preliminary, Phase A
Include:
- Business drivers
- Stakeholders
- Architecture vision
- High-level solution overview
For any missing information, explicitly state: "⚠️ Information not available in solution metadata."
For any assumptions made, explicitly state: "⚠️ Assumption: [description]."
---
### 02_Business_Architecture.md
**TOGAF:** Phase B
Include:
- Business capabilities
- Business processes
- Mapping to Power Automate flows
---
### 03_Application_Architecture.md
**TOGAF:** Phase C (Application)
Include:
- Power Apps overview
- Power Automate flows
- Custom connectors
- Application interaction diagrams (Mermaid required)
---
### 04_Data_Architecture.md
**TOGAF:** Phase C (Data)
Include:
- Dataverse usage
- Core tables
- Relationships
- Data ownership
For default Dataverse tables, explicitly state: "Default Dataverse table '[table name]' used. No custom metadata available."
---
### 05_Technology_Architecture.md
**TOGAF:** Phase D
Include:
- Power Platform environments
- Azure dependencies
- Identity and access (Microsoft Entra ID)
---
### 06_Security_and_Integration.md
**TOGAF:** Cross-cutting
Include:
- Security roles and model
- Compliance considerations
- Integration patterns
Do not include:
- Accounts or crendentials
- Sensitive information not available in solution metadata
---
### 07_Deployment_and_Governance.md
**TOGAF:** Phase G, H (Governance & Change)
Include:
- ALM strategy
- CI/CD approach
- Architecture governance
---
### 08_Appendix.md
Include:
- Glossary
- Abbreviations
- External references
---
## 6. Diagram Rules
- Use **Mermaid** for all diagrams
- Diagrams MUST be embedded in the relevant section
- Every diagram MUST include a title and description
Example:
```mermaid
graph TD
User --> PowerApp
PowerApp --> Dataverse
Dataverse --> Flow
```
---
## 7. Content Rules (STRICT)
- No undocumented assumptions
- Any assumption MUST be explicitly stated with "⚠️ Assumption: [description]."
- Clearly distinguish baseline vs target
- Use formal, neutral language
- Explicitly state missing information
---
## 8. Quality Criteria
Documentation MUST be:
- TOGAF-traceable
- Consistent across files
- Suitable for architecture review boards
- Easy to extend to a full ADM deliverable set
---
## 9. Constraints
- Read-only analysis
- No deployment or configuration changes
- No inferred business intent beyond solution metadata
---
## 10. Versioning
Each file MUST include:
- Version
- Date
- Author (Agent)
- Change summary
---
If you want to read more about setting up agents.md files, check out the https://agents.md/, all you need to do is load the file in the root of your repo and you are good to go.
The actual instruction to the agent is almost boring: Write proper architecture documentation for solution ‘xxxx’
From there, the agent follows the instructions in the agents.md file to produce the documentation.
- Exports the solution
- Extracts it
- Analyzes all components
- Maps them to TOGAF domains
- And produces a structured documentation set
And if you read thourhgh the documentation you can see that it follows the structure we defined, and it flags assumptions and missing information as well. It is not perfect, but it is a great starting point for documentation, including some diagrams that make it easier to convey your messsage and clearly flagging things that are not identified in the source code or metadata.
Why this works for me
I spend less time doing “documentation work”, I can start the agent, grab a coffee, and when I return I have a first draft of the documentation ready to go. From there I can tweak and adjust, but the hard work of gathering the information and structuring it is already done. It does miss some of the context that only a human can provide, but if all went smooth that is already flagged in the documentation as well using the ⚠️ icon.
That way instead of dreading the documentation part of a project, I can now focus on reviewing and improving the content instead of gathering it. I still don’t like it, and it is not perfect, but it is a huge step forward.
Together with the team you work you might want to make sure you all agree on the structure of the documentation, and perhaps spend a little time coming up with a design for your markdown files, but that is a one-time effort that pays off in the long run.
Albert-Jan Schot
CTO, Microsoft MVP & FastTrack Recognized Solution Architect
I am Albert-Jan Schot, CTO at Blis Digital, Microsoft MVP, and FastTrack Recognized Solution Architect focused on Microsoft 365, Azure, and AI agents. I help teams turn complex Microsoft Cloud challenges into practical architecture decisions and shipped outcomes.
Zuid Holland, Netherlands
