Skip to content

Commit 4865468

Browse files
KSemenenkoKSemenenko
committed
update agetnt + credits
1 parent 796de15 commit 4865468

File tree

3 files changed

+232
-204
lines changed

3 files changed

+232
-204
lines changed

‎CREDITS.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Credits
2+
3+
## Contributors
4+
5+
- [Managed Code](https://www.managed-code.com) — Framework design and development
6+
7+
8+
## Special Thanks
9+
10+
- **[Roger Johansson](https://www.linkedin.com/in/roger-johansson-4a4bb61/)** — His post about self-learning agents inspired the Conversations (Self-Learning) mechanism that became the core of MCAF
11+
12+
---
13+
14+
*Want to contribute? Open a PR or issue on [GitHub](https://github.com/managedcode/MCAF).*

‎TUTORIAL.md‎

Lines changed: 129 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -8,61 +8,143 @@ A practical guide to implementing MCAF in your repository.
88

99
Get MCAF running in your repository:
1010

11-
1. Create documentation structure in `docs/`
12-
2. Copy `AGENTS.md` template to repository root
13-
3. Define `build`, `test`, `format` commands
14-
4. Set up test environment for integration tests
15-
5. Configure CI pipeline
11+
1. Bootstrap AGENTS.md with AI analysis
12+
2. Create documentation structure in `docs/`
13+
3. Document existing features
14+
4. Create ADRs for existing decisions
15+
5. Write feature docs before coding (ongoing workflow)
16+
6. Set up test environment
17+
7. Configure CI pipeline
1618

1719
---
1820

19-
## Step 1: Documentation Structure
21+
## Step 1: Bootstrap AGENTS.md
2022

21-
Create folders under `docs/`:
23+
Copy the AGENTS.md template to your repository root. The AI agent will analyze your project and fill in the template with actual commands, patterns, and conventions found in your codebase.
2224

23-
- `Features/` — feature specifications with test flows
24-
- `ADR/` — Architecture Decision Records
25-
- `Testing/` — test strategy and execution guides
26-
- `Development/` — local setup and workflow
25+
**What you get:** A customized AGENTS.md with your tech stack, build commands, code style, and workflow patterns.
2726

28-
Optional folders as needed:
27+
**Prompt:**
2928

30-
- `API/` — endpoint documentation
31-
- `Architecture/` — system diagrams
32-
- `Operations/` — deployment and monitoring
33-
34-
Start small. Add folders as your project grows.
29+
```
30+
Analyze this project and fill in AGENTS.md:
31+
32+
1. Detect tech stack — language, framework, versions from config files
33+
2. Scan codebase — folders, modules, layers, architecture
34+
3. Read existing code — patterns, conventions, naming styles
35+
4. Check git history — commit message format, branch naming, team patterns
36+
5. Find existing docs — README, comments with rules, ADRs if exist
37+
6. Analyze tests — structure, frameworks, how organized
38+
39+
Fill each AGENTS.md section:
40+
- Project name and detected stack
41+
- Commands — actual build/test/format commands
42+
- Task Delivery — workflow based on git patterns
43+
- Testing — rules based on test structure
44+
- Code Style — conventions from existing code
45+
- Boundaries — protected/critical areas
46+
47+
Keep Self-Learning section as-is.
48+
Report what you found.
49+
```
3550

3651
---
3752

38-
## Step 2: Configure AGENTS.md
53+
## Step 2: Create Documentation Structure
54+
55+
Create a `docs/` folder with subfolders for different types of documentation. This gives AI agents and developers a clear place to find and add documentation.
56+
57+
**What you get:** Organized folder structure ready for feature specs, ADRs, and development guides.
58+
59+
**Prompt:**
3960

40-
Copy the AGENTS.md template to your repository root.
61+
```
62+
Create documentation structure for this project:
63+
64+
1. Create docs/ folder with subfolders:
65+
- docs/Features/ — for feature specifications
66+
- docs/ADR/ — for architecture decisions
67+
- docs/Testing/ — for test strategy
68+
- docs/Development/ — for setup and workflow
69+
- docs/API/ — for API documentation (if applicable)
70+
71+
2. Create docs/Development/setup.md with:
72+
- How to clone and run the project
73+
- Required tools and versions
74+
- Environment setup steps
75+
76+
3. Create docs/Testing/strategy.md with:
77+
- Test structure found in project
78+
- How to run tests
79+
- Test categories (unit/integration/e2e)
80+
81+
Report what you created.
82+
```
83+
84+
---
85+
86+
## Step 3: Document Existing Features
4187

42-
Customize:
88+
Scan the codebase for major features and modules, then create documentation for each. This captures current behavior so AI agents understand what already exists before making changes.
4389

44-
1. Replace `{{ProjectName}}` and `{{Stack}}` with your values
45-
2. Add project-specific rules in Section 2
46-
3. Define actual commands in Section 7
47-
4. Add team preferences in Section 8
90+
**What you get:** Feature docs in `docs/Features/` describing purpose, flows, components, and tests for each major feature.
4891

49-
Commands section example:
92+
**Prompt:**
5093

51-
```markdown
52-
- build: `dotnet build`
53-
- test: `dotnet test`
54-
- format: `dotnet format`
94+
```
95+
Document existing features in this project:
96+
97+
1. Scan codebase for major features/modules
98+
2. For each feature create docs/Features/{feature-name}.md with:
99+
- Purpose — what it does
100+
- Main flows — how it works
101+
- Components — files/classes involved
102+
- Tests — what tests exist for it
103+
- Current behavior — how it behaves now
104+
105+
Use template from docs/templates/Feature-Template.md if exists.
106+
List all features you documented.
55107
```
56108

57-
Update this file whenever you discover new patterns or receive feedback.
109+
---
110+
111+
## Step 4: Create ADRs for Existing Decisions
112+
113+
Document architectural decisions that were already made in the project. This prevents AI agents from suggesting changes that conflict with existing architecture.
114+
115+
**What you get:** ADRs in `docs/ADR/` explaining why the database, framework, auth approach, and other technical choices were made.
116+
117+
**Prompt:**
118+
119+
```
120+
Create ADRs for architectural decisions found in this project:
121+
122+
1. Analyze codebase for architectural patterns:
123+
- Database choice
124+
- Framework choice
125+
- Authentication approach
126+
- API structure
127+
- Any significant technical decisions
128+
129+
2. For each decision create docs/ADR/{number}-{title}.md with:
130+
- Status: Accepted (already implemented)
131+
- Context: Why this decision was needed
132+
- Decision: What was chosen
133+
- Consequences: Trade-offs
134+
135+
Use template from docs/templates/ADR-Template.md if exists.
136+
List all ADRs you created.
137+
```
58138

59139
---
60140

61-
## Step 3: Write Feature Docs
141+
## Step 5: Write Feature Docs (Ongoing Workflow)
142+
143+
For new features, write documentation before coding. This is your ongoing workflow after bootstrap.
62144

63-
Before implementing a feature, create a doc in `docs/Features/`.
145+
**What you get:** Clear specification that both humans and AI agents can implement without guessing.
64146

65-
Include:
147+
**Include:**
66148

67149
- Feature name and purpose
68150
- Business rules and constraints
@@ -77,11 +159,13 @@ Feature docs should be precise enough that:
77159

78160
---
79161

80-
## Step 4: Set Up Integration Tests
162+
## Step 6: Set Up Tests
81163

82-
Integration tests are the backbone of MCAF.
164+
Integration tests are the backbone of MCAF. Configure your test environment to use real dependencies instead of mocks.
83165

84-
Principles:
166+
**What you get:** Test infrastructure that catches real integration issues, not just unit-level bugs.
167+
168+
**Principles:**
85169

86170
- Use real dependencies, not mocks
87171
- Internal systems (database, cache, queues) run in containers
@@ -91,17 +175,21 @@ Principles:
91175
For .NET projects, consider:
92176

93177
- Aspire for container orchestration
94-
- TUnit or xUnit for test framework
95-
- WebApplicationFactory for API tests
178+
- TUnit for test framework
179+
- WebApplicationFactory for Integration tests
96180
- Playwright for UI tests
97181

98182
The specific tools matter less than the principle: test real behaviour with real dependencies.
99183

100184
---
101185

102-
## Step 5: Configure CI
186+
## Step 7: Configure CI
187+
188+
Set up CI to run all tests automatically. This ensures every PR is verified before merge.
189+
190+
**What you get:** Automated quality gate that runs build, tests, and static analysis.
103191

104-
CI pipeline should:
192+
**CI pipeline should:**
105193

106194
- Build the solution
107195
- Run all tests (unit, integration, API, UI)
@@ -160,7 +248,7 @@ Yes. MCAF is language-agnostic. Define your <code>build</code>, <code>test</code
160248
<details class="faq-item">
161249
<summary>Do I need all documentation folders?</summary>
162250
<div class="faq-answer">
163-
Start with <code>Features/</code>, <code>ADR/</code>, and <code>Development/</code>. Add others as needed.
251+
Start with <code>Features/</code>, <code>ADR/</code>, <code>Testing/</code>, and <code>Development/</code>. Add others as needed.
164252
</div>
165253
</details>
166254

0 commit comments

Comments
 (0)