diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..80a9d3747
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,63 @@
+# Contributing to yedir-ai
+
+Thank you for contributing. yedir-ai is maintained as a production-oriented AI design workspace, so changes should be easy to review, safe to roll back, and supported by clear verification evidence.
+
+## Development Setup
+
+Use Node.js 20 and pnpm 9.12.3.
+
+```bash
+pnpm install
+cp .env.example .env.local
+pnpm db:migrate
+AUTH_TRUST_HOST=true PORT=3001 pnpm dev
+```
+
+Never commit `.env.local` or real credentials.
+
+## Branches and Commits
+
+- Use focused branches for a single theme, such as `refactor/settings-local-ai` or `chore/log-hygiene-canvas`.
+- Keep commits small enough to review and revert independently.
+- Do not mix broad formatting changes with functional changes.
+- Do not push generated local artifacts, worktrees, swap files, migration backups, or `tsconfig.tsbuildinfo`.
+
+## Change Scope
+
+Prefer narrow, explicit scopes:
+
+- UI changes should preserve existing product behavior unless the PR states otherwise.
+- API changes must describe compatibility impact and response-shape changes.
+- Settings changes must preserve existing setting keys, SWR keys, and save semantics unless a migration is included.
+- Logging/security changes must avoid exposing prompts, URLs, base64 data, provider payloads, user content, tokens, cookies, or signed URLs.
+
+`/api/chat` is currently an internal Canvas/Agent generation API. Do not treat it as a public legacy Chat UI contract unless the PR explicitly migrates callers.
+
+## Required Checks
+
+Before opening or updating a PR, run:
+
+```bash
+pnpm check:quality
+AUTH_TRUST_HOST=true PORT=3001 pnpm dev
+SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
+```
+
+`pnpm check:quality` covers lint, scoped log hygiene, typecheck, diff hygiene, and tracked artifact checks.
+
+If a route or workflow cannot be tested locally, explain the gap in the PR.
+
+## Pull Requests
+
+Use the PR template and include:
+
+- What changed and why.
+- The user or operational impact.
+- Verification output or screenshots when relevant.
+- Any intentional follow-up work.
+
+For frontend changes, include screenshots or a short visual verification note. For route/API changes, include status codes, response-shape notes, or targeted test evidence.
+
+## Security
+
+Follow `SECURITY.md` for vulnerability reporting and sensitive-data handling. Report suspected vulnerabilities privately; do not open public issues for secrets, auth bypasses, signed URL leaks, or data exposure.
diff --git a/README.md b/README.md
index 674d67261..bf75efebb 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,7 @@ tests/                       Playwright e2e and route-level tests
 - [系统架构说明](docs/architecture.md)
 - [发布就绪检查清单](docs/release-readiness.md)
 - [安全策略](SECURITY.md)
+- [贡献指南](CONTRIBUTING.md)
 
 ## 开发边界
 
diff --git a/docs/release-readiness.md b/docs/release-readiness.md
index 04aed3143..6af5fd29f 100644
--- a/docs/release-readiness.md
+++ b/docs/release-readiness.md
@@ -26,6 +26,7 @@ SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
 - 高风险日志链路已纳入 `pnpm check:logs`，禁止回流裸 `console.*`。
 - CI 基础门禁与本地 `pnpm check:quality` 使用同一套污染物检查脚本。
 - 安全披露、敏感信息和日志规则以根目录 `SECURITY.md` 为准。
+- 分支、提交、PR 和验证要求以根目录 `CONTRIBUTING.md` 为准。
 
 ## 不应在发布包中出现