Skip to content

Commit 911f364

Browse files
nisha-bitonisha-bito
authored
Updated BitoAIArchitectGuidelines.md for clarity and structure
Updated BitoAIArchitectGuidelines.md for clarity and structure
2 parents a977fb1 + 1fee1e4 commit 911f364

2 files changed

Lines changed: 162 additions & 36 deletions

File tree

‎BitoAIArchitectGuidelines.md‎

Lines changed: 156 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,168 @@
1-
# BitoAIArchitect MCP - Usage Instructions
1+
# Architecture-Grounded Instructions
22

3-
## Rule: Always Call BitoAIArchitect Tools First
3+
## Core Principle
44

5-
**For ANY question about code, repos, architecture, features, or implementation:**
6-
- Call BitoAIArchitect tools IMMEDIATELY (don't ask permission)
7-
- Use IN PARALLEL with local file exploration
8-
- BitoAIArchitect has indexed data local tools can't see
5+
**ALWAYS use BitoAIArchitect MCP for architecture knowledge — whether generating code OR answering questions about the system.**
96

10-
## When to Use (Auto-Trigger)
7+
BitoAIArchitect has indexed data that local file exploration can't see (dependencies, relationships, architecture patterns across repos, clusters, technology stacks).
118

12-
Call BitoAIArchitect when user asks about:
13-
- Repositories, services, projects, codebases
14-
- "What can/does", "is there", "do we have", "find"
15-
- Architecture, design, patterns, structure
16-
- Dependencies, integrations, relationships
17-
- Tech stack, frameworks, libraries
18-
- "How to implement/add/create/build"
19-
- "Where is/should", "which repo"
9+
---
2010

21-
## Tools
11+
## When to Engage Architecture Knowledge (Auto-Trigger)
2212

23-
**Always start with:**
24-
- `searchRepositories` - Find repos by keyword/tech/functionality
25-
- `getRepositoryInfo` - Get repo details (current or any other)
26-
- `listRepositories` - Browse all available repos
13+
### For Code Generation:
14+
- User asks about implementation, creation, building, or "how to"
15+
- Code will interact with APIs, services, or dependencies
16+
- Following existing patterns matters (consistency, compatibility)
17+
- Understanding system boundaries or architecture is relevant
2718

28-
**Use when relevant:**
29-
- `listClusters` - See grouped services
30-
- `getClusterInfo` - Understand multi-repo relationships
19+
### For Architecture/Repository Exploration:
20+
- User asks about repositories, services, or system components
21+
- Questions about dependencies or relationships between repos/services
22+
- Questions about technology stacks, frameworks, or patterns used
23+
- Questions about clusters, subsystems, or architectural groupings
24+
- Any "what", "which", "how does X relate to Y" architecture questions
25+
- Exploring the codebase structure or organization
26+
- Questions like "what repos do we have?", "show me dependencies", "how is X architected?"
3127

32-
## Quick Rules
28+
---
3329

34-
✅ Call BitoAIArchitect + explore local files in parallel
35-
✅ Use searchRepositories for "is there/do we have" questions
36-
✅ Check getRepositoryInfo even if repo seems obvious
37-
✅ Never ask permission - just call tools
30+
## Architecture Exploration Workflow
3831

39-
❌ Never skip BitoAIArchitect because you see local files
40-
❌ Never ask "Would you like me to search?"
32+
**For pure exploration/questions (not code generation):**
4133

42-
**BitoAIArchitect knows:** What repos exist, dependencies, tech stacks, capabilities, architecture
43-
**Local files show:** Implementation details, current code
34+
1. **Use BitoAIArchitect as PRIMARY source:**
35+
- `listRepositories` — discover all repos in the organization
36+
- `searchRepositories` — find repos by technology, functionality, or keywords
37+
- `getRepositoryInfo` — get detailed info including dependencies
38+
- `listClusters` / `getClusterInfo` — understand architectural groupings
39+
- `searchWithinRepository` — find specific information within a repo
40+
- `getRepositorySchema` — understand repo structure
41+
- `queryFieldAcrossRepositories` — compare patterns across repos
42+
- `searchCode` / `searchSymbols` — find code patterns across the system
43+
44+
2. **Supplement with local files if needed** for implementation details
45+
46+
3. **Present findings** with clear structure showing relationships and patterns
47+
48+
---
49+
50+
## Pre-Code-Generation Checklist (CRITICAL)
51+
52+
**ALWAYS attempt to use BitoAIArchitect tools IN PARALLEL with local file exploration:**
53+
54+
1. **API Endpoint Verification** ← MANDATORY
55+
- What are the ACTUAL endpoint paths? (Don't assume REST conventions)
56+
- How is the session/context passed? (URL path? Header? Query param?)
57+
- What is the actual request body format?
58+
- What is the actual response format? (JSON object? Streaming? SSE?)
59+
- Are there required headers or authentication?
60+
- FIND ACTUAL ROUTE/ENDPOINT DEFINITIONS in the codebase
61+
62+
2. **Request/Response Format Evidence** ← MANDATORY
63+
- Find working examples of API calls (tests, client code, docs)
64+
- Check actual response structure with real data
65+
- Verify special formats (streaming, chunked, etc.)
66+
- Look for middleware or interceptors that transform data
67+
- DON'T assume standard REST or JSON response patterns
68+
69+
3. **Pattern Grounding**
70+
- Find 2-3 existing implementations that call the same API
71+
- Study HOW they do it, not just WHAT they do
72+
- Understand architectural patterns (error handling, structure, library choices)
73+
- Look for conventions specific to this codebase
74+
75+
4. **Type/Contract Understanding**
76+
- What types/interfaces does the API work with?
77+
- Are there shared models, enums, or constants?
78+
- What does the actual function signature look like elsewhere?
79+
- What edge cases or special handling exists?
80+
81+
5. **Architectural Alignment**
82+
- Does this code belong in the right service/repo?
83+
- Does it respect service boundaries and relationships?
84+
- Are there subsystem or cluster considerations?
85+
86+
6. **Local Implementation Details**
87+
- How are similar patterns actually coded in this specific codebase?
88+
- What libraries, idioms, or conventions are used?
89+
- Copy the STYLE and APPROACH of existing code
90+
91+
---
92+
93+
## Search Strategy for API Code
94+
95+
When writing code that calls APIs:
96+
97+
1. **Search for endpoint definitions first**
98+
- Look for route files, controller files, handler files
99+
- Find the actual path and method
100+
101+
2. **Search for request format examples**
102+
- Look for: headers, authentication, etc.
103+
- Find test files that call the endpoint
104+
- Look for client code already calling this endpoint
105+
106+
3. **Search for response format examples**
107+
- Look for response parsing code
108+
- Find test assertions on response structure
109+
110+
4. **VERIFY BEFORE CODING**
111+
- Don't generate until you've seen actual examples
112+
- If endpoints don't match REST conventions, verify the actual pattern
113+
- Check for response and how it's parsed
114+
115+
---
116+
117+
## How to Generate Code
118+
119+
1. **Use BitoAIArchitect IN PARALLEL with local file exploration** to gather architecture context
120+
- BitoAIArchitect provides: architecture, dependencies, repo relationships, patterns across system
121+
- Local files provide: implementation details, exact syntax, conventions, actual API definitions
122+
2. **VERIFY the API contract BEFORE writing code**
123+
- Find actual endpoint definition
124+
- Find actual request/response examples
125+
- Look for existing code calling the same endpoint
126+
3. **Study the pattern** from both sources
127+
4. **Generate based on evidence** — follow the patterns you found
128+
5. **Validate alignment** — does it match the architecture and style you studied?
129+
130+
---
131+
132+
## Key Principles
133+
134+
✅ **Use BitoAIArchitect for ALL architecture questions** — repos, dependencies, relationships, patterns
135+
✅ **Use BitoAIArchitect + local files IN PARALLEL** — both are needed for complete answers
136+
✅ **VERIFY API contracts first** — find actual endpoint definitions and examples before coding
137+
✅ **Find working examples** — don't assume patterns, find them in existing code
138+
✅ **Search for special handling** — any special handling different from the norm, etc.
139+
✅ **Never ask permission** — just call BitoAIArchitect, don't ask "would you like me to search?"
140+
✅ **Grounded**: Generated code follows evidence from the codebase
141+
✅ **Consistent**: Follows existing patterns, conventions, and architectural decisions
142+
143+
❌ **Never** skip BitoAIArchitect because you see local files
144+
❌ **Never** skip BitoAIArchitect for architecture/repo questions — it's the primary source
145+
❌ **Never** assume API structure based on REST conventions—verify actual implementation
146+
❌ **Never** generate code without finding actual endpoint definitions
147+
❌ **Never** assume response format—find examples of real responses
148+
❌ **Never** ask permission — "Would you like me to search?" is not allowed
149+
❌ **Never** ignore existing patterns "because it would work either way"
150+
151+
---
152+
153+
## BitoAIArchitect Quick Reference
154+
155+
| Question Type | Primary Tool(s) |
156+
|--------------|-----------------|
157+
| "What repos do we have?" | `listRepositories` |
158+
| "Find repos using X technology" | `searchRepositories` |
159+
| "What are the dependencies of repo X?" | `getRepositoryInfo` with `includeOutgoingDependencies=true` |
160+
| "What depends on repo X?" | `getRepositoryInfo` with `includeIncomingDependencies=true` |
161+
| "How are repos grouped/clustered?" | `listClusters`, `getClusterInfo` |
162+
| "Find code pattern across repos" | `searchCode`, `searchSymbols` |
163+
| "Compare field across repos" | `queryFieldAcrossRepositories` |
164+
| "What's the structure of repo X?" | `getRepositorySchema` |
165+
| "Find X within repo Y" | `searchWithinRepository` |
166+
167+
---
44168

45-
**Use BOTH for complete answers.**

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,10 @@
6868
<a href="#8-troubleshooting-guide">Troubleshooting guide</a>
6969
</li>
7070
<li>
71-
<a href="#9-support--contact">Support & contact</a>
71+
<a href="#9-upgrading-ai-architect">Upgrading AI Architect</a>
72+
</li>
73+
<li>
74+
<a href="#10-support--contact">Support & contact</a>
7275
</li>
7376
</ol>
7477
</details>
@@ -215,7 +218,7 @@ Once the indexing is complete, you can configure AI Architect MCP server in any
215218

216219
### Step 1- Download AI Architect
217220

218-
Download the latest version of AI Architect package from our **[GitHub repository](https://github.com/gitbito/ai-architect/blob/main/bito-ai-architect-1.2.0.tar.gz)**.
221+
Download the latest version of AI Architect package from our **[GitHub repository](https://github.com/gitbito/ai-architect/releases)**.
219222

220223
---
221224

@@ -662,7 +665,7 @@ To switch between deployment types (Docker to Kubernetes or Kubernetes to Docker
662665

663666
<!-- Support & contact -->
664667

665-
## 9. Support & contact
668+
## 10. Support & contact
666669

667670
For comprehensive information and guidance on the AI Architect, including installation and configuration instructions, please refer to our detailed **[documentation available here](https://docs.bito.ai/ai-architect/overview)**. Should you require further assistance or have any inquiries, our support team is readily available to assist you.
668671

0 commit comments

Comments
 (0)