Agent skill

moai-cc-claude-md

Authoring CLAUDE.md Project Instructions. Design project-specific AI guidance, document workflows, define architecture patterns. Use when creating CLAUDE.md files for projects, documenting team standards, or establishing AI collaboration guidelines.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/testing/moai-cc-claude-md

SKILL.md

Skill Metadata

Field Value
Version 1.0.0
Tier Ops
Auto-load When authoring CLAUDE.md files

What It Does

프로젝트별 CLAUDE.md 파일 작성을 위한 표준 구조와 패턴을 제공합니다. AI 협업 가이드라인, 워크플로우 문서화, 아키텍처 패턴 정의 방법을 다룹니다.

When to Use

  • 새 프로젝트의 CLAUDE.md 파일을 생성할 때
  • 기존 CLAUDE.md를 업데이트하거나 개선할 때
  • 팀 표준 및 개발 워크플로우를 문서화할 때
  • AI 협업 패턴을 정의할 때

Authoring CLAUDE.md Project Instructions

CLAUDE.md is a Markdown file that provides Claude with project-specific context, workflows, standards, and guidance. It acts as a living document for AI collaboration patterns.

CLAUDE.md File Location & Purpose

Location: ./{PROJECT_ROOT}/CLAUDE.md or /~/.claude/CLAUDE.md (personal)

Purpose: Tell Claude about your project before every session starts.

Core Sections

Section 1: Project Overview

markdown
# Project Name

**Description**: What does this project do?

**Repository**: GitHub URL
**Tech Stack**: Technologies, languages, frameworks
**Team**: Size, roles
**Status**: Active, archived, experimental

Section 2: Core Workflow

markdown
## Development Workflow

### Phase 1: Planning
- Use `/alfred:1-plan` for SPEC creation
- EARS syntax: Ubiquitous, Event-driven, State-driven, Optional, Constraints
- Store in `.moai/specs/`

### Phase 2: Implementation (TDD)
- RED: Write failing tests
- GREEN: Minimal implementation
- REFACTOR: Improve quality
- Tools: pytest, TypeScript, mypy, ruff

### Phase 3: Sync & Documentation
- Run `/alfred:3-sync` to validate
- Update Living Documents
- Verify @TAG chains
- Prepare PR

Section 3: Code Standards

markdown
## Code Standards (TRUST 5 Principles)

### T - Test First
- Target coverage: ≥ 85%
- Framework: pytest for Python, Jest for TypeScript
- Pattern: TDD (RED → GREEN → REFACTOR)

### R - Readable
- Max file: 300 LOC
- Max function: 50 LOC
- Max params: 5
- Use linters: ruff (Python), ESLint (TypeScript)

### U - Unified
- Type safety: mypy for Python, TypeScript strict mode
- Consistent patterns across domain
- Shared utilities in `src/core/`

### S - Secured
- Input validation everywhere
- No hardcoded secrets
- Use environment variables
- Run: bandit (Python), npm audit

### T - Trackable
- @TAG system: @SPEC:ID, @TEST:ID, @CODE:ID, @DOC:ID
- Document all changes in HISTORY section
- Link code to SPEC requirements

Section 4: Project Architecture

markdown
## Architecture

### Directory Structure

src/ ├── core/ # Shared utilities, domain models ├── domain/ # Business logic, DOMAIN-specific ├── interfaces/ # API endpoints, CLI commands ├── middleware/ # Cross-cutting concerns └── infra/ # Database, external services

tests/ ├── unit/ # Unit tests for core/ and domain/ ├── integration/ # API, database tests └── e2e/ # End-to-end workflows


### Key Design Decisions
- Monolithic backend (for now)
- Database: PostgreSQL with migrations
- Authentication: JWT tokens
- API: REST with OpenAPI docs

Section 5: AI Collaboration Patterns

markdown
## Working with Claude Code

### When to Use Sub-agents
- `debug-helper`: Errors, test failures, exceptions
- `security-auditor`: Vulnerability assessment, OWASP checks
- `architect`: Refactoring, system design, scalability
- `code-reviewer`: Quality analysis, SOLID violations

### Commands Available
- `/alfred:1-plan "feature description"` — Create SPEC
- `/alfred:2-run SPEC-ID` — Implement (TDD)
- `/alfred:3-sync` — Sync docs and validate
- `/review-code src/**/*.ts` — Code review
- `/deploy [env]` — Deploy pipeline

### Context Engineering Tips
- Always mention relevant SPEC ID
- Provide file paths relative to project root
- Link to similar existing features
- Mention constraints or non-negotiables upfront

Section 6: Known Gotchas & Decisions

markdown
## Important Notes

### Why We Use SPEC-First
- Clarifies requirements upfront
- Prevents scope creep
- Enables parallel work (different SPECs)
- Makes code changes traceable

### Common Mistakes to Avoid
- ❌ Implementing without SPEC
- ❌ Skipping tests for "quick" fixes
- ❌ Mixing multiple features in one PR
- ❌ Ignoring @TAG system

### Team Decisions
- Use pytest fixtures for mocking (not monkeypatch)
- All API responses must include status codes
- Database migrations are CI/CD blocking
- Security audit runs on every PR

CLAUDE.md Examples by Domain

Example 1: Web API Project

markdown
# Transaction API

**Tech Stack**: Python (FastAPI), PostgreSQL, pytest

## Phase Workflow

1. **SPEC**: Requirements in EARS syntax
   - Example: `The API must validate transaction amounts > 0`
   - Stored in: `.moai/specs/SPEC-TRANS-{###}/spec.md`

2. **TDD**: Implement with test-first approach
   - Tests: `tests/integration/test_transactions.py`
   - Code: `src/domain/transaction.py`

3. **Sync**: Verify completeness
   - Run: `/alfred:3-sync`
   - Check: TAG chain integrity

Example 2: React Frontend Project

markdown
# Competition Dashboard

**Tech Stack**: TypeScript, React 19, Vitest, Tailwind

## Development Standards

- Framework: Next.js 15 (App Router)
- Testing: Vitest + React Testing Library
- Styling: Tailwind CSS with shadcn/ui
- State: Zustand for client state, Server Components for data

## Key Patterns
- Server Components for data fetching
- Suspense boundaries for loading states
- Error boundaries for graceful failures

High-Freedom: Architectural Decisions

markdown
## Why This Architecture?

### Monolith vs Microservices
- **Chosen**: Monolithic backend
- **Reason**: Team < 10, throughput manageable
- **When to reconsider**: >10M requests/month or 3+ teams

### Database: PostgreSQL
- **Reason**: Strong ACID guarantees, mature ecosystem
- **Alternatives considered**: MongoDB (rejected: unclear schema)

Medium-Freedom: Workflow Definition

markdown
## Code Review Checklist

Before merging, reviewer must verify:
1. [ ] SPEC ID linked in PR description
2. [ ] All tests passing (>85% coverage)
3. [ ] No security issues (bandit clean)
4. [ ] Code follows TRUST 5 principles
5. [ ] @TAG chain complete (@SPEC → @TEST → @CODE → @DOC)
6. [ ] CHANGELOG updated

Low-Freedom: Explicit Rules

markdown
## Non-negotiable Rules

- ❌ No commits without @TAG references
- ❌ No merging PRs without passing tests
- ❌ No pushing secrets to repo
- ❌ No force-pushing to main/master
- ✅ All features must have SPEC document
- ✅ All code changes must have corresponding tests
- ✅ All SPECs must use EARS syntax

Validation Checklist

  • Project name and description clear
  • Tech stack documented
  • Development workflow defined (Plan → Run → Sync)
  • TRUST 5 principles explained
  • Architecture diagram or structure described
  • AI collaboration patterns defined
  • Known gotchas documented
  • Examples provided for key workflows

Best Practices

✅ DO:

  • Keep CLAUDE.md up-to-date as standards evolve
  • Include real examples (links to actual files/PRs)
  • Document why (not just what)
  • Link to external docs (architecture decisions, security policy)
  • Review with team before finalizing

❌ DON'T:

  • Explain general programming concepts (Claude already knows)
  • List every possible workflow (focus on your specific patterns)
  • Write as instruction to humans (write as guidance to Claude)
  • Update CLAUDE.md only at project start (evolve as needed)

Reference: Claude Code CLAUDE.md documentation Version: 1.0.0

Didn't find tool you were looking for?

Be as detailed as possible for better results