├── .gitignore ├── img ├── codebase-context.png └── codebase-diagram.mermaid ├── .devcontainer ├── build.sh └── devcontainer.json ├── .contextignore ├── .vscode └── launch.json ├── .github └── ISSUE_TEMPLATE │ ├── feature_request.md │ └── bug_report.md ├── LICENSE.md ├── .context └── index.md ├── CODEBASE-CONTEXT.md └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | __pycache__ 3 | .aider* 4 | .mypy_cache 5 | -------------------------------------------------------------------------------- /img/codebase-context.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Agentic-Insights/codebase-context-spec/HEAD/img/codebase-context.png -------------------------------------------------------------------------------- /.devcontainer/build.sh: -------------------------------------------------------------------------------- 1 | cd linters/typescript 2 | npm install 3 | npm run build 4 | cd ../.. 5 | cd examples/context-editor 6 | npm install 7 | npm start 8 | cd ../.. 9 | -------------------------------------------------------------------------------- /.contextignore: -------------------------------------------------------------------------------- 1 | # Development artifacts 2 | node_modules/ 3 | .git/ 4 | .vscode/ 5 | 6 | # Build outputs 7 | dist/ 8 | build/ 9 | 10 | # Temporary files 11 | *.log 12 | *.tmp 13 | .DS_Store 14 | 15 | # Keep all documentation and specification files 16 | !*.md 17 | !img/ 18 | -------------------------------------------------------------------------------- /.vscode/launch.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "0.2.0", 3 | "configurations": [ 4 | { 5 | "type": "node", 6 | "request": "launch", 7 | "name": "Debug CSS", 8 | "program": "${workspaceFolder}/linters/typescript/dist/cli.js", 9 | "args": ["${workspaceFolder}"], 10 | "cwd": "${workspaceFolder}", 11 | "console": "integratedTerminal", 12 | "internalConsoleOptions": "neverOpen" 13 | } 14 | ] 15 | } -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /img/codebase-diagram.mermaid: -------------------------------------------------------------------------------- 1 | graph TD 2 | subgraph "Codebase Context Specification" 3 | Root[Root Directory] 4 | Spec[Specification CODEBASE-CONTEXT.md] 5 | MainDoc[Main Documentation README.md] 6 | Examples[Examples Directory] 7 | Editor[Context Editor] 8 | 9 | Root --> Spec 10 | Root --> MainDoc 11 | Root --> Examples 12 | Examples --> Editor 13 | end 14 | 15 | subgraph "Context Editor" 16 | EditorApp[React Application] 17 | EditorTests[Tests] 18 | EditorREADME[Editor README] 19 | 20 | Editor --> EditorApp 21 | Editor --> EditorTests 22 | Editor --> EditorREADME 23 | end 24 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | 31 | **Smartphone (please complete the following information):** 32 | - Device: [e.g. iPhone6] 33 | - OS: [e.g. iOS8.1] 34 | - Browser [e.g. stock browser, safari] 35 | - Version [e.g. 22] 36 | 37 | **Additional context** 38 | Add any other context about the problem here. 39 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Copyright 2024 Agentic Insights, LLC. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 4 | 5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 6 | 7 | THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the 2 | // README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node 3 | { 4 | "name": "Node.js & TypeScript", 5 | // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile 6 | "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm", 7 | "features": { 8 | "ghcr.io/devcontainers/features/go:1": {} 9 | }, 10 | 11 | // Features to add to the dev container. More info: https://containers.dev/features. 12 | // "features": {}, 13 | 14 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 15 | "forwardPorts": [13000], 16 | 17 | // Use 'postCreateCommand' to run commands after the container is created. 18 | "postCreateCommand": "build.sh" 19 | 20 | // Configure tool-specific properties. 21 | // "customizations": {}, 22 | 23 | // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. 24 | // "remoteUser": "root" 25 | } 26 | -------------------------------------------------------------------------------- /.context/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | module-name: "codebase-context-spec" 3 | description: "Core specification for the Codebase Context standard" 4 | version: "1.1.0-RFC" 5 | technologies: 6 | - "Markdown" 7 | related-modules: 8 | - name: "@codebase-context/cc-cli" 9 | description: "Official CLI tool for working with CCS" 10 | repository: "https://www.npmjs.com/package/@codebase-context/cc-cli" 11 | status: "active" 12 | --- 13 | 14 | # Codebase Context Specification Repository 15 | 16 | This repository contains the core specification for the Codebase Context standard. It is intentionally minimal, serving primarily as the canonical reference for the CCS format and implementation guidelines. 17 | 18 | ## Repository Structure 19 | 20 | The repository consists of: 21 | - `CODEBASE-CONTEXT.md`: The main specification document 22 | - `README.md`: Project overview and documentation 23 | - `img/`: Supporting diagrams and visual assets 24 | 25 | ## Related Tools 26 | 27 | The primary implementation tool for this specification is the `@codebase-context/cc-cli` package, which provides command-line utilities for: 28 | - Creating and managing .context directories 29 | - Validating context files against the specification 30 | - Generating context documentation 31 | 32 | For implementation details and usage, visit the [cc-cli package on NPM](https://www.npmjs.com/package/@codebase-context/cc-cli). 33 | -------------------------------------------------------------------------------- /CODEBASE-CONTEXT.md: -------------------------------------------------------------------------------- 1 | # Codebase Context Specification (CCS) 2 | 3 | ## Document Information 4 | - **Version:** 1.1-RFC 5 | - **Date:** 2024-12-06 6 | - **Status:** Draft 7 | 8 | ## Overview 9 | 10 | The Codebase Context Specification (CCS) establishes a standardized framework for documenting and communicating codebase context to both human developers and artificial intelligence systems. Through a structured directory approach, CCS enables teams to maintain comprehensive project documentation that enhances collaboration between developers and AI tools. 11 | 12 | ## 1. Core Structure 13 | 14 | The specification defines a `.context` directory as the central location for all contextual information about a project. This directory must be present at the root of the project and may exist at the root of any significant submodule or component. 15 | 16 | A standard `.context` directory contains: 17 | 18 | ``` 19 | .context/ 20 | ├── index.md # Primary context file with project overview 21 | ├── docs.md # Detailed documentation 22 | └── diagrams/ # Visual documentation in Mermaid format 23 | ├── architecture.mmd 24 | └── data-flow.mmd 25 | ``` 26 | 27 | ## 2. Context Files 28 | 29 | ### 2.1 index.md Structure 30 | 31 | The index.md file serves as the primary entry point for context information. It must include YAML front matter with the following structure: 32 | 33 | ```yaml 34 | --- 35 | module-name: "Project Name" 36 | description: "Comprehensive project description" 37 | related-modules: 38 | - name: Simple example project root 39 | path: ./examples/simple 40 | - name: CLI tool (dotcontext) 41 | path: https://github.com/Agentic-Insights/dotcontext 42 | architecture: 43 | style: "Architecture style" 44 | components: 45 | - name: "Component Name" 46 | description: "Component description" 47 | patterns: 48 | - name: "Pattern Name" 49 | usage: "Pattern usage description" 50 | --- 51 | ``` 52 | 53 | The remainder of index.md should provide a clear narrative overview of the project, its architecture, and key implementation details. 54 | 55 | To better understand the specification and its implementation, please refer to the example repositories showcasing the CCS in action. 56 | 57 | ### 2.2 docs.md Purpose 58 | 59 | The docs.md file contains detailed documentation about specific aspects of the project, including: 60 | 61 | 1. Development guidelines and best practices 62 | 2. Business domain information 63 | 3. Technical implementation details 64 | 4. Integration patterns 65 | 5. Troubleshooting guides 66 | 67 | ## 3. AI Tool Integration 68 | 69 | The specification is designed for straightforward integration with AI development tools. Tool developers can implement support through one of two approaches: 70 | 71 | ### 3.1 Simple Integration 72 | 73 | For basic integration, tools can add the following instruction to their prompt or context: 74 | 75 | "Before starting a task, if a .context directory exists, read it for an architectural overview and project context starting at .context/index.md" 76 | 77 | This approach enables immediate compatibility without requiring complex tooling changes. 78 | 79 | ### 3.2 Advanced Integration 80 | 81 | For more sophisticated integration, tools should: 82 | 83 | 1. Parse the YAML front matter for structured data 84 | 2. Process Mermaid diagrams for visual understanding 85 | 3. Index documentation content for contextual awareness 86 | 4. Track context hierarchy through project structure 87 | 88 | ## 4. Context Hierarchy 89 | 90 | Context information follows a hierarchical structure through the project: 91 | 92 | 1. Root level: Project-wide architecture and standards 93 | 2. Module level: Component-specific implementations 94 | 3. Feature level: Detailed implementation context 95 | 96 | Each level inherits context from its parent while adding its own specific information. 97 | 98 | ## 5. Best Practices 99 | 100 | ### Documentation Quality 101 | 102 | The effectiveness of the specification relies on maintaining high-quality documentation: 103 | 104 | 1. Keep language clear and precise 105 | 2. Update documentation alongside code changes 106 | 3. Include relevant examples and explanations 107 | 4. Maintain consistency in terminology 108 | 5. Regular review and validation of context information 109 | 110 | ### Content Organization 111 | 112 | Organize content to maximize clarity and accessibility: 113 | 114 | 1. Use clear section headings 115 | 2. Maintain logical information grouping 116 | 3. Include visual diagrams for complex concepts 117 | 4. Cross-reference related documentation 118 | 5. Keep individual files focused and concise 119 | 120 | ## 6. Implementation Guide 121 | 122 | To implement the specification in a project: 123 | 124 | 1. Create the `.context` directory at the project root 125 | 2. Initialize index.md with required metadata 126 | 3. Document key architectural decisions 127 | 4. Add relevant diagrams in Mermaid format 128 | 5. Establish documentation update processes 129 | 6. Configure development tools for context awareness 130 | 131 | ## 7. Security Considerations 132 | 133 | Protect sensitive information while maintaining useful context: 134 | 135 | 1. Never include credentials or secrets 136 | 2. Avoid detailed security implementation details 137 | 3. Use appropriate access controls 138 | 4. Regular security review of context content 139 | 140 | ## 8. Version Control 141 | 142 | Maintain context documentation effectively: 143 | 144 | 1. Include .context directory in version control 145 | 2. Review context changes during code review 146 | 3. Update context files atomically with related code changes 147 | 4. Maintain change history for context evolution 148 | 149 | ## Appendix A: Migration 150 | 151 | For projects using version 1.0 of the specification: 152 | 153 | 1. Create the `.context` directory 154 | 2. Move content from .context.md to .context/index.md 155 | 3. Restructure documentation into appropriate files 156 | 4. Update any tool configurations 157 | 5. Remove deprecated .context.md files 158 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Codebase Context Specification (CCS) v 1.1.0-RFC 2 | 3 | ![Codebase Context Image](./img/codebase-context.png "Codebase Context Specification") 4 | 5 | ## Introduction 6 | 7 | Welcome to the [Codebase Context Specification (CCS)](./CODEBASE-CONTEXT.md) repository! This project establishes a standardized method for embedding rich contextual information within codebases to enhance understanding for both AI and human developers. By providing a clear and consistent way to communicate project structure, conventions, and key concepts, we significantly improve code comprehension and facilitate more effective collaboration between humans and AI in software development. 8 | 9 | ## Quick Links 10 | 11 | - [Official Website](https://codebasecontext.org) 12 | - [Full Specification (CODEBASE-CONTEXT.md)](./CODEBASE-CONTEXT.md) 13 | - [GitHub Repository](https://github.com/Agentic-Insights/codebase-context-spec) 14 | - [NPM Package](https://www.npmjs.com/package/dotcontext) 15 | - [SubStack Article by Vaskin](https://agenticinsights.substack.com/p/codebase-context-specification-rfc) 16 | 17 | ## Installation & Usage 18 | 19 | For installation and usage instructions of the Codebase Context CLI tool, visit the [@codebase-context/cc-cli package](https://www.npmjs.com/package/@codebase-context/cc-cli) on NPM. 20 | 21 | ## Supported Node.js Versions 22 | 23 | This project supports the following Node.js versions: 24 | 25 | - Node.js 18.x 26 | - Node.js 20.x 27 | - Node.js 22.x 28 | 29 | We recommend using the latest LTS (Long Term Support) version of Node.js for optimal performance and security. 30 | 31 | ## Codebase Context: A New Convention 32 | 33 | The Codebase Context Specification introduces a convention similar to `.env` and `.editorconfig` systems, but focused on documenting your code for both AI and humans. Just as `.env` files manage environment variables and `.editorconfig` ensures consistent coding styles, CCS uses a `.context` directory with an `index.md` file (and optionally `.context.yaml`, `.context.json`) to provide a standardized way to capture and communicate the context of your codebase. 34 | 35 | This convention allows developers to: 36 | 1. Document high-level architecture and design decisions 37 | 2. Explain project-specific conventions and patterns 38 | 3. Highlight important relationships between different parts of the codebase 39 | 4. Provide context that might not be immediately apparent from the code itself 40 | 41 | By adopting this convention, teams can ensure that both human developers and AI assistants have access to crucial contextual information, leading to better code understanding, more accurate suggestions, and improved overall development efficiency. 42 | 43 | ## Key Concepts 44 | 45 | - **Contextual Metadata**: Structured information about the project, its components, and conventions, designed for both human and AI consumption. 46 | - **AI-Human Collaborative Documentation**: Guidelines for creating documentation that's easily parsed by AI models while remaining human-readable and maintainable. 47 | - **Standardized Context Directory**: Consistent use of `.context` directories containing `index.md` (and optionally `.yaml` and `.json` files) for conveying codebase context at various levels (project-wide, directory-specific, etc.). 48 | - **Context-Aware Development**: Encouraging a development approach that considers and documents the broader context of code, not just its immediate functionality. 49 | 50 | ## Recent Updates 51 | 52 | We've recently updated our dependencies to address security vulnerabilities and improve compatibility with different Node.js versions. If you encounter any issues after updating, please report them in our GitHub issues. 53 | 54 | ## Using with AI Assistants 55 | 56 | The [CODING-ASSISTANT-PROMPT.md](./CODING-ASSISTANT-PROMPT.md) file provides guidelines for AI assistants to understand and use the Codebase Context Specification. This allows for immediate adoption of the specification without requiring specific tooling integration. 57 | 58 | To use the Codebase Context Specification with an AI assistant: 59 | 60 | 1. Include the content of CODING-ASSISTANT-PROMPT.md in your prompt to the AI assistant. 61 | 2. Ask the AI to analyze your project's context files based on these guidelines. 62 | 3. The AI will be able to provide more accurate and context-aware responses by following the instructions in the prompt. 63 | 64 | Note that while this approach allows for immediate use of the specification, some features like .contextignore should eventually be applied by tooling for more robust implementation. 65 | 66 | ## Tooling Recommendations 67 | 68 | Developers are encouraged to create: 69 | 70 | - Memory systems using git branches as storage 71 | - IDE plugins for context file creation and editing 72 | - AI model integrations for parsing and utilizing context 73 | - Tools for aggregating and presenting project-wide context 74 | - Agents that can help create context in codebases that are blank 75 | - Codebase summarizers, submodule summarizers 76 | - Memory systems that take advantage of the context 77 | - Continuous TODO monitors that can re-try implementations / solutions 78 | 79 | ## Future Directions 80 | 81 | 1. Integration with existing documentation systems 82 | 2. Dynamic context generation through code analysis 83 | 3. Potential support for explicit context overriding 84 | 4. Agent tool / context matching and references 85 | 86 | ## Contribution / RFC Process 87 | 88 | We welcome contributions and feedback from the community to help shape the final specification. Here's how you can get involved: 89 | 90 | 1. **Review the Specification**: Start by thoroughly reading the current specification in CODEBASE-CONTEXT.md. 91 | 2. **Open an Issue**: For suggestions, questions, or concerns, open an issue in this repository. 92 | 3. **Submit a Pull Request**: For proposed changes or additions, submit a pull request with a clear description of your modifications. 93 | 4. [**Join the Discussion**](https://github.com/Agentic-Insights/codebase-context-spec/discussions): Participate in open discussions and provide your insights on existing issues and pull requests. 94 | 95 | All contributions will be reviewed and discussed openly. Significant changes may go through an RFC (Request for Comments) process to ensure thorough consideration and community input. 96 | 97 | ## Version History 98 | 99 | - 1.0.0-RFC: Initial RFC release of the Codebase Context Specification 100 | 101 | ## Learn More 102 | 103 | For a deeper dive into the Codebase Context Specification, check out this [SubStack article by Vaskin](https://agenticinsights.substack.com/p/codebase-context-specification-rfc), the author of the specification. 104 | --------------------------------------------------------------------------------