Provide a high-level overview of the project, including its purpose, scope, and major components. Describe the general structure of the codebase and the separation of concerns between different layers (e.g., client, server, shared utilities).
Document the key commands for interacting with the project during development and deployment. This may include:
- Static analysis and code quality checks
- Code formatting and auto-fixing tools
- Running tests (full suite or specific files)
- Starting the application in development mode
- Building the application for production
- Previewing the production build locally
Outline the local development environment setup. Specify default ports, service endpoints, and any tools that developers need to run locally (e.g., web servers, databases, caches). This section helps contributors quickly get up and running.
Define the conventions and standards for writing code in the project. Include:
- Formatting rules (e.g., indentation, quote style, line length)
- Naming conventions (e.g., variable names, acronym casing)
- Preferred commenting/documentation style
- Prohibited practices (e.g., suppressing errors without explanation)
- Guidelines on language features and patterns to encourage consistency and readability
Describe the project's testing strategy and tools. Include:
- Types of testing used (e.g., unit, integration, end-to-end)
- Naming conventions and file organization for test files
- Best practices for writing tests
- Guidance on how to mock dependencies and isolate units of work
- How to run specific test cases or test suites
Provide an overview of the software architecture. Describe the key components, design patterns, and layers used in the system. Highlight how the application is structured in terms of data flow, user interactions, state management, and external integrations.
List the security principles and practices that must be followed in the project. Include:
- How sensitive data should be handled
- Secure storage of secrets (e.g., via environment variables)
- Input validation and sanitization practices
- Secure transport and communication requirements
- Dependency management and update policies
- Authorization and access control principles
Define the conventions for version control. Include:
- Required checks before committing (e.g., linting, testing, type checks)
- Branching and merging strategy
- Rules for force-pushing (e.g., restrictions on main branches)
- Commit message conventions or automation practices
- How to manage code reviews and pull requests
Explain how configuration is managed in the project. Include:
- Where environment variables or external configs are declared and documented
- How configuration schemas are structured and validated
- Where to update documentation when adding new configuration options
Ensure naming conventions are followed consistently, and every config option is discoverable and documented for contributors.