main @ 938fdf8190-100
+75-89
+60-74
+40-59
+0-39
+Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants
+ + +# Option 1: Standalone CLAUDE.md
+touch CLAUDE.md
+# Add content describing your project
+
+# Option 2: Symlink CLAUDE.md to AGENTS.md
+touch AGENTS.md
+# Add content to AGENTS.md
+ln -s AGENTS.md CLAUDE.md
+
+# Option 3: @ reference in CLAUDE.md
+echo '@AGENTS.md' > CLAUDE.md
+touch AGENTS.md
+# Add content to AGENTS.md# Standalone CLAUDE.md (Option 1)
+
+## Overview
+Brief description of what this project does.
+
+## Architecture
+Key patterns and structure.
+
+## Development
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## Coding Standards
+- Use TypeScript strict mode
+- Follow ESLint configuration
+- Write tests for new features
+# CLAUDE.md with @ reference (Option 3)
+@AGENTS.md
+# AGENTS.md (shared by multiple tools)
+
+## Project Overview
+This project implements a REST API for user management.
+
+## Architecture
+- Layered architecture: controllers, services, repositories
+- PostgreSQL database with SQLAlchemy ORM
+- FastAPI web framework
+
+## Development Workflow
+```bash
+# Setup
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Run tests
+pytest
+
+# Start server
+uvicorn app.main:app --reload
+```
+
+## Code Conventions
+- Use type hints for all functions
+- Follow PEP 8 style guide
+- Write docstrings for public APIs
+- Maintain >80% test coverage
+Add type annotations to function signatures
+ + +# Python
+pip install mypy
+mypy --strict src/
+
+# TypeScript
+npm install --save-dev typescript
+echo '{"compilerOptions": {"strict": true}}' > tsconfig.json# Python - Before
+def calculate(x, y):
+ return x + y
+
+# Python - After
+def calculate(x: float, y: float) -> float:
+ return x + y
+// TypeScript - tsconfig.json
+{
+ "compilerOptions": {
+ "strict": true,
+ "noImplicitAny": true,
+ "strictNullChecks": true
+ }
+}
+Organize code into standard directories (src/, tests/, docs/)
+ + +mkdir -p src tests docs
+# Move source files to src/
+# Move test files to tests/Add more security scanning tools for comprehensive coverage
+ + +gh repo edit --enable-security
+pip install detect-secrets # Python secret detection
+npm audit # JavaScript dependency audit# .github/dependabot.yml
+version: 2
+updates:
+ - package-ecosystem: pip
+ directory: /
+ schedule:
+ interval: weeklyConfigure conventional commits with commitlint
+ + +npm install --save-dev @commitlint/cli @commitlint/config-conventional huskyRefactor large files into smaller, focused modules
+ + +# Split large file:
+# models.py (1500 lines) → models/user.py, models/product.py, models/order.pyRefactor code to improve separation of concerns
+ + +# Good: Feature-based organization
+project/
+├── auth/
+│ ├── login.py
+│ ├── signup.py
+│ └── tokens.py
+├── users/
+│ ├── profile.py
+│ └── preferences.py
+└── billing/
+ ├── invoices.py
+ └── payments.py
+
+# Bad: Layer-based organization
+project/
+├── models/
+│ ├── user.py
+│ ├── invoice.py
+├── views/
+│ ├── user_view.py
+│ ├── invoice_view.py
+└── controllers/
+ ├── user_controller.py
+ ├── invoice_controller.py
+Make documentation more concise and structured
+ + +# Check README length
+wc -l README.md
+
+# Count headings
+grep -c '^#' README.md# Good: Concise with structure
+
+## Quick Start
+```bash
+pip install -e .
+agentready assess .
+```
+
+## Features
+- Fast repository scanning
+- HTML and Markdown reports
+- 25 agent-ready attributes
+
+## Documentation
+See [docs/](docs/) for detailed guides.
+# Bad: Verbose prose
+
+This project is a tool that helps you assess your repository
+against best practices for AI-assisted development. It works by
+scanning your codebase and checking for various attributes that
+make repositories more effective when working with AI coding
+assistants like Claude Code...
+
+[Many more paragraphs of prose...]
+Add docstrings to public functions and classes
+ + +# Install pydocstyle
+pip install pydocstyle
+
+# Check docstring coverage
+pydocstyle src/
+
+# Generate documentation
+pip install sphinx
+sphinx-apidoc -o docs/ src/# Python - Good docstring
+def calculate_discount(price: float, discount_percent: float) -> float:
+ """Calculate discounted price.
+
+ Args:
+ price: Original price in USD
+ discount_percent: Discount percentage (0-100)
+
+ Returns:
+ Discounted price
+
+ Raises:
+ ValueError: If discount_percent not in 0-100 range
+
+ Example:
+ >>> calculate_discount(100.0, 20.0)
+ 80.0
+ """
+ if not 0 <= discount_percent <= 100:
+ raise ValueError("Discount must be 0-100")
+ return price * (1 - discount_percent / 100)
+// JavaScript - Good JSDoc
+/**
+ * Calculate discounted price
+ *
+ * @param {number} price - Original price in USD
+ * @param {number} discountPercent - Discount percentage (0-100)
+ * @returns {number} Discounted price
+ * @throws {Error} If discountPercent not in 0-100 range
+ * @example
+ * calculateDiscount(100.0, 20.0)
+ * // Returns: 80.0
+ */
+function calculateDiscount(price, discountPercent) {
+ if (discountPercent < 0 || discountPercent > 100) {
+ throw new Error("Discount must be 0-100");
+ }
+ return price * (1 - discountPercent / 100);
+}
+Install with: pip install radon
+ + +Create Architecture Decision Records (ADRs) directory and document key decisions
+ + +# Create ADR directory
+mkdir -p docs/adr
+
+# Create first ADR using template
+cat > docs/adr/0001-use-architecture-decision-records.md << 'EOF'
+# 1. Use Architecture Decision Records
+
+Date: 2025-11-22
+
+## Status
+Accepted
+
+## Context
+We need to record architectural decisions made in this project.
+
+## Decision
+We will use Architecture Decision Records (ADRs) as described by Michael Nygard.
+
+## Consequences
+- Decisions are documented with context
+- Future contributors understand rationale
+- ADRs are lightweight and version-controlled
+EOF# Example ADR Structure
+
+```markdown
+# 2. Use PostgreSQL for Database
+
+Date: 2025-11-22
+
+## Status
+Accepted
+
+## Context
+We need a relational database for complex queries and ACID transactions.
+Team has PostgreSQL experience. Need full-text search capabilities.
+
+## Decision
+Use PostgreSQL 15+ as primary database.
+
+## Consequences
+- Positive: Robust ACID, full-text search, team familiarity
+- Negative: Higher resource usage than SQLite
+- Neutral: Need to manage migrations, backups
+```
+Add structured logging library for machine-parseable logs
+ + +# Install structlog
+pip install structlog
+
+# Configure structlog
+# See examples for configuration# Python with structlog
+import structlog
+
+# Configure structlog
+structlog.configure(
+ processors=[
+ structlog.stdlib.add_log_level,
+ structlog.processors.TimeStamper(fmt="iso"),
+ structlog.processors.JSONRenderer()
+ ]
+)
+
+logger = structlog.get_logger()
+
+# Good: Structured logging
+logger.info(
+ "user_login",
+ user_id="123",
+ email="user@example.com",
+ ip_address="192.168.1.1"
+)
+
+# Bad: Unstructured logging
+logger.info(f"User {user_id} logged in from {ip}")
+Create OpenAPI specification for API endpoints
+ + +# Install OpenAPI validator
+npm install -g @stoplight/spectral-cli
+
+# Validate spec
+spectral lint openapi.yaml
+
+# Generate client SDK
+npx @openapitools/openapi-generator-cli generate \
+ -i openapi.yaml \
+ -g python \
+ -o client/# openapi.yaml - Minimal example
+openapi: 3.1.0
+info:
+ title: My API
+ version: 1.0.0
+ description: API for managing users
+
+servers:
+ - url: https://api.example.com/v1
+
+paths:
+ /users/{userId}:
+ get:
+ summary: Get user by ID
+ parameters:
+ - name: userId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: User found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/User'
+ '404':
+ description: User not found
+
+components:
+ schemas:
+ User:
+ type: object
+ required:
+ - id
+ - email
+ properties:
+ id:
+ type: string
+ example: "user_123"
+ email:
+ type: string
+ format: email
+ example: "user@example.com"
+ name:
+ type: string
+ example: "John Doe"
+Configure 3 missing linter(s)
+ + +npm install --save-dev eslint && npx eslint --init
+npm install --save-dev markdownlint-cli && touch .markdownlint.json# .pylintrc example
+[MASTER]
+max-line-length=100
+
+[MESSAGES CONTROL]
+disable=C0111# .eslintrc.json example
+{
+ "extends": "eslint:recommended",
+ "rules": {
+ "no-console": "warn"
+ }
+}Improve container configuration
+ + +docker build -t myapp .
+docker-compose up -d# .dockerignore example
+.git
+.venv
+__pycache__
+*.pyc
+.env
+node_modules# Multi-stage Dockerfile example
+FROM node:18 AS builder
+WORKDIR /app
+COPY . .
+RUN npm ci && npm run build
+
+FROM node:18-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+CMD ["node", "dist/index.js"]