Skip to content

Commit af17b2b

Browse files
killerappkillerapp
authored
feat: new specification for codebase context
1 parent 009d4e7 commit af17b2b

File tree

1 file changed

+333
-2
lines changed

1 file changed

+333
-2
lines changed

‎README.md‎

Lines changed: 333 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,333 @@
1-
# codebase-context-spec
2-
Proposal for a flexible, tool-agnostic, codebase context system that helps teach AI coding tools about your codebase. Super easy to get started, just create a .context.md file in the root of your project.
1+
# AI Context Convention Specification
2+
3+
Version: 1.0-preview
4+
Date: 2024-08-31
5+
6+
## 1. Overview
7+
8+
The AI Context Convention is a standardized method for embedding rich contextual information within codebases to enhance AI-assisted development. This specification outlines a flexible, language-agnostic approach to providing both structured and unstructured context at various levels of a project.
9+
10+
## 2. Key Principles
11+
12+
1. **Flexibility**: Support multiple file formats and context types.
13+
2. **Proximity**: Keep context close to the code it describes.
14+
3. **Hierarchy**: Allow for project-wide, directory-level, and file-specific context.
15+
4. **Clarity**: Promote clear, maintainable context files.
16+
5. **AI-Centric**: Optimize for AI model consumption and interpretation.
17+
18+
## 3. File Structure
19+
20+
### 3.1 File Names
21+
22+
Context files must use one of the following extensions:
23+
24+
- `.context.md`: Markdown format (default, supports both structured and unstructured content)
25+
- `.context.yaml` or `.context.yml`: YAML format
26+
- `.context.json`: JSON format
27+
28+
The `.md` extension is the default and recommended format as it supports both structured (via YAML front matter) and unstructured content.
29+
30+
### 3.2 File Locations
31+
32+
Context files can be placed at two levels within a project:
33+
34+
- Project root: For project-wide context
35+
- Directories: For context specific to that directory and its contents
36+
37+
Example structure:
38+
39+
```
40+
project_root/
41+
├── .context.md
42+
├── .contexignore
43+
├── .contextdocs.md
44+
├── src/
45+
│ ├── .context.yaml
46+
│ ├── module1/
47+
│ │ └── .context.md
48+
│ └── module2/
49+
│ └── .context.json
50+
└── tests/
51+
└── .context.md
52+
```
53+
54+
## 4. File Formats
55+
56+
### 4.1 Markdown Format (Default)
57+
58+
Markdown files (.context.md) are the default and recommended format. They can include an optional YAML front matter for structured data, followed by free-form Markdown content.
59+
60+
Example:
61+
62+
```markdown
63+
---
64+
description: Core application logic
65+
conventions:
66+
- Use camelCase for variable names
67+
- Each function should have a single responsibility
68+
aiPrompts:
69+
- Focus on performance optimizations
70+
- Suggest ways to improve error handling
71+
fileContexts:
72+
auth.js:
73+
description: Authentication module
74+
aiPrompts:
75+
- Review security measures
76+
- Suggest improvements for password hashing
77+
data.js:
78+
description: Data processing module
79+
conventions:
80+
- Use async/await for all database operations
81+
---
82+
83+
# Core Application Logic
84+
85+
This directory contains the core logic for our application, including user authentication and data processing.
86+
87+
## Authentication Module (auth.js)
88+
89+
The authentication module handles user login, registration, and password reset functionality. It uses bcrypt for password hashing and JWT for session management.
90+
91+
Key considerations:
92+
- OWASP security best practices
93+
- GDPR compliance for data handling
94+
95+
## Data Processing Module (data.js)
96+
97+
The data processing module is responsible for all database interactions and data transformations. It uses an ORM for database operations and implements caching for improved performance.
98+
99+
Performance considerations:
100+
- Optimize database queries
101+
- Implement efficient data structures for in-memory operations
102+
```
103+
104+
### 4.2 YAML Format
105+
106+
YAML format (.context.yaml or .context.yml) can be used as an alternative to Markdown for purely structured data.
107+
108+
Example:
109+
110+
```yaml
111+
description: Core application logic
112+
conventions:
113+
- Use camelCase for variable names
114+
- Each function should have a single responsibility
115+
aiPrompts:
116+
- Focus on performance optimizations
117+
- Suggest ways to improve error handling
118+
fileContexts:
119+
auth.js:
120+
description: Authentication module
121+
aiPrompts:
122+
- Review security measures
123+
- Suggest improvements for password hashing
124+
data.js:
125+
description: Data processing module
126+
conventions:
127+
- Use async/await for all database operations
128+
```
129+
130+
### 4.3 JSON Format
131+
132+
JSON format (.context.json) can be used for purely structured data when preferred.
133+
134+
Example:
135+
136+
```json
137+
{
138+
"description": "Core application logic",
139+
"conventions": [
140+
"Use camelCase for variable names",
141+
"Each function should have a single responsibility"
142+
],
143+
"aiPrompts": [
144+
"Focus on performance optimizations",
145+
"Suggest ways to improve error handling"
146+
],
147+
"fileContexts": {
148+
"auth.js": {
149+
"description": "Authentication module",
150+
"aiPrompts": [
151+
"Review security measures",
152+
"Suggest improvements for password hashing"
153+
]
154+
},
155+
"data.js": {
156+
"description": "Data processing module",
157+
"conventions": [
158+
"Use async/await for all database operations"
159+
]
160+
}
161+
}
162+
}
163+
```
164+
165+
## 5. Context Accumulation
166+
167+
1. Context accumulates as you traverse deeper into the directory structure.
168+
2. More specific contexts provide additional detail to broader contexts.
169+
3. AI models should consider all relevant context files, prioritizing more specific contexts when appropriate.
170+
4. There is no strict overriding; AI judges context relevance based on the query or task.
171+
172+
## 6. The .contexignore File
173+
174+
The `.contexignore` file, placed in the project root, excludes files or directories from context consideration.
175+
176+
### Syntax
177+
178+
- Uses glob patterns similar to `.gitignore`
179+
- Lines starting with `#` are comments
180+
181+
Example:
182+
```
183+
# Ignore all .log files
184+
*.log
185+
186+
# Ignore the entire build directory
187+
build/
188+
189+
# Ignore all .test.js files
190+
**/*.test.js
191+
192+
# Ignore a specific file
193+
src/deprecated-module.js
194+
195+
# Ignore all files in any directory named 'temp'
196+
**/temp/*
197+
```
198+
199+
## 7. Security Considerations
200+
201+
1. Avoid including sensitive information (API keys, passwords) in context files.
202+
2. Be cautious with proprietary algorithms or trade secrets.
203+
3. Use `.gitignore` to exclude sensitive context files from version control if necessary.
204+
205+
## 8. The .contextdocs File
206+
207+
The `.contextdocs` file allows developers to specify external documentation sources that should be incorporated into the project's context. This feature is particularly useful for including documentation from dependencies, libraries, or related projects.
208+
209+
### 8.1 Location and Naming
210+
211+
- The `.contextdocs` file should be placed in the root directory of the project.
212+
- It must use one of the following extensions:
213+
- `.contextdocs.md` (default, recommended)
214+
- `.contextdocs.yaml` or `.contextdocs.yml`
215+
- `.contextdocs.json`
216+
217+
### 8.2 File Structure
218+
219+
The `.contextdocs` file should contain an array of documentation sources. Each source can be:
220+
221+
- A file path relative to the project root
222+
- A URL to a markdown file
223+
- A package name with associated documentation files
224+
225+
### 8.3 Examples
226+
227+
#### Markdown Format (.contextdocs.md) - Default
228+
229+
```markdown
230+
---
231+
documentation:
232+
- type: local
233+
path: docs/project_overview.md
234+
- type: url
235+
url: https://raw.githubusercontent.com/example/repo/main/API.md
236+
- type: package
237+
name: express
238+
version: 4.17.1
239+
docs:
240+
- README.md
241+
- docs/api.md
242+
- docs/guide/routing.md
243+
---
244+
245+
# Additional Documentation Notes
246+
247+
This section can include any free-form text to provide context about the listed documentation sources, their relevance to the project, or any other pertinent information.
248+
```
249+
250+
#### YAML Format (.contextdocs.yaml)
251+
252+
```yaml
253+
documentation:
254+
- type: local
255+
path: docs/project_overview.md
256+
- type: url
257+
url: https://raw.githubusercontent.com/example/repo/main/API.md
258+
- type: package
259+
name: express
260+
version: 4.17.1
261+
docs:
262+
- README.md
263+
- docs/api.md
264+
- docs/guide/routing.md
265+
```
266+
267+
#### JSON Format (.contextdocs.json)
268+
269+
```json
270+
{
271+
"documentation": [
272+
{
273+
"type": "local",
274+
"path": "docs/project_overview.md"
275+
},
276+
{
277+
"type": "url",
278+
"url": "https://raw.githubusercontent.com/example/repo/main/API.md"
279+
},
280+
{
281+
"type": "package",
282+
"name": "express",
283+
"version": "4.17.1",
284+
"docs": [
285+
"README.md",
286+
"docs/api.md",
287+
"docs/guide/routing.md"
288+
]
289+
}
290+
]
291+
}
292+
```
293+
294+
### 8.4 Behavior
295+
296+
- When an AI model or related tool is processing the project context, it should fetch and incorporate the specified documentation.
297+
- For local files, the content should be read from the specified path.
298+
- For URLs, the content should be fetched from the provided URL.
299+
- For packages, the documentation should be fetched from the package's repository or documentation site, based on the package name and version.
300+
301+
### 8.5 Use Cases
302+
303+
- Including documentation for key dependencies
304+
- Referencing company-wide coding standards or guidelines
305+
- Incorporating design documents or architectural overviews
306+
- Linking to relevant external resources or tutorials
307+
308+
### 8.6 Considerations
309+
310+
- Ensure that URLs point to stable, version-controlled documentation to maintain consistency.
311+
- Be mindful of the total volume of documentation to avoid overwhelming the AI model with irrelevant information.
312+
- Regularly review and update the `.contextdocs` file to ensure all referenced documentation remains relevant and up-to-date.
313+
- Consider implementing caching mechanisms for external documentation to improve performance and reduce network requests.
314+
315+
## 9. Tooling Recommendations
316+
317+
Developers are encouraged to create:
318+
319+
1. Linters and validators for context files
320+
2. IDE plugins for context file creation and editing
321+
3. AI model integrations for parsing and utilizing context
322+
4. Tools for aggregating and presenting project-wide context
323+
324+
## 10. Future Directions
325+
326+
1. Standardized query language for context interrogation
327+
2. Integration with existing documentation systems
328+
3. Dynamic context generation through code analysis
329+
4. Potential support for explicit context overriding
330+
331+
## 11. Conclusion
332+
333+
The AI Context Convention provides a flexible, standardized approach to enriching codebases with contextual information for AI models. By adopting this convention, development teams can enhance AI-assisted workflows, improving code quality and development efficiency across projects of any scale or complexity. The addition of the `.contextdocs` file further enriches the available context by allowing the incorporation of external documentation, ensuring that AI models have access to comprehensive information about the project and its dependencies.

0 commit comments

Comments
 (0)